Identity providers in UAA

You can configure identity providers (IDPs) with your Cloud Foundry User Account and Authentication (UAA) server.

LDAP providers

The Lightweight Directory Access Protocol communicates with directory servers. Compared with the other external IDPs, LDAP is a very simple integration. It only requires configuration on UAA. Other types of provider require that you make configuration changes on both UAA and on the external provider.

LDAP supports three different connection types:

ldap://: Cleartext LDAP, typically over port 389
ldaps://: An SSL/TLS connection, typically over port 636
ldap:// with StartTLS: A TLS handshake performed on a cleartext LDAP connection, typically over port 389

For more information, see User Account and Authentication LDAP Integration in the UAA repository on GitHub.

SAML providers

The SAML v2 standard is a dominant player in the federated authentication space. It is one of the harder integrations to configure. When configuring SAML integration on UAA, you must configure both UAA and the SAML IDP. A mistake on either side causes assertions to be rejected and authentication to fail.

OpenID Connect providers

The OpenID Connect standard is a simple identity layer on top of the OAuth 2.0 protocol. Clients can verify the identity of the end-user based on the authentication performed by the OIDC IDP, as well as to obtain basic profile information about the end-User in an interoperable and REST-like manner. When configuring OIDC integration on UAA, you must configure both UAA and the OIDC IDP. A mistake on either side causes tokens to be rejected and authentication to fail.

Service provider versus identity provider

The SAML and OIDC specifications define two players in their protocol interaction:

Service provider (SP), the server that receives the assertion. This is typically UAA.
Identity provider (IDP), the server that receives the authentication request, authenticates the user and sends the assertion or token to the SP.

UAA can be configured to act as an SP or IDP. In most scenarios, UAA is the SP, and an external provider, such as Okta or Azure Directory or SAP Cloud Identity Services, is the IDP.

View metadata

A SAML provider, either the SP or the IDP, presents a set of metadata. This metadata contains information about the server and is used to configure the opposing provider.

If you use UAA as an SP, you can download metadata through the /saml/metadata endpoint of your SAML provider. For example, http://login.example.com/saml/metadata. Metadata is in XML format. Using this information, you can configure the IDP.

If you use UAA as an IDP, fetch the metadata from the /saml/idp/metadata endpoint. For example, http://login.example.com/saml/idp/metadata.

SAML IDP workflow

SAML provides two commonly used workflows: * SP-initiated * IDP-initiated.

The following sections describe each workflow.

SAML SP-initiated

If you go to the UAA login page and click a link to authenticate using your organization’s SAML provider, you are using an SP-initiated flow.

The SP sends an authentication request to the IDP. See the following example:


 xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" AssertionConsumerServiceURL="https://..host../saml/SSO/alias/login.identity.cf-app.com" Destination="http://simplesamlphp.identity.cf-app.com/saml2/idp/SSOService.php" ForceAuthn="false" ID="a17j41337a9835i93h78hihc9a89j4b" IsPassive="false" IssueInstant="2017-05-03T21:16:15.989Z" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Version="2.0" > <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> Login.identity.cf-app.com 
   saml2:Issuer>
  <saml2p:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" />
</saml2p:AuthnRequest>

After the IDP has authenticated the user, it sends an assertion back to the user. This step takes place in both SP-initiated and IDP-initiated flows. For information about the SAML response, see IDP-Initiated.

Data flows between Service Provider and User Agent, and between User Agent and Identity Provider.

SAML IDP-initiated

You can start your authentication process with the IDP.

The IDP sends a SAML assertion to the SP, which in this case is UAA, similar to the following example:

<?xml version="1.0" encoding="UTF-8"?>
<samlp:Response
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    Destination="https://...url.../saml/SSO/alias/login.identity.cf-app.com"
    ID="_de497bc8a79e5f17202a30112181ea7c99325f8827"
    InResponseTo="a17j41337a9835i93h78hihc9a89j4b"
    IssueInstant="2017-05-03T21:51:01Z" Version="2.0">
  <saml:Issuer>
    http://simplesamlphp.identity.cf-app.com/saml2/idp/metadata.php
  </saml:Issuer>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>
      <ds:CanonicalizationMethod
        Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
      <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
      <ds:Reference URI="#_de497bc8a79e5f17202a30112181ea7c99325f8827">
        <ds:Transforms>
          <ds:Transform
            Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
          <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
        
 ds:Transforms>
        <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <ds:DigestValue>QQZHHBC4KDxZ0H4FrbTGFOnNR1E=<\/ds:DigestValue>
      </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>...signature value...<\/ds:SignatureValue>
    <ds:KeyInfo>
      <ds:X509Data>
        <ds:X509Certificate>...x509 certificate value<\/ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </ds:Signature>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
  </samlp:Status>
  <saml:Assertion
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    ID="_ec6adc4fca9e3dc72fff4a1fd99561007777ac7afd"
    IssueInstant="2017-05-03T21:51:01Z"
    Version="2.0">
<saml:Issuer>http://simplesamlphp.identity.cf-app.com/saml2/idp/metadata.php<\/saml:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:SignedInfo>
        <ds:CanonicalizationMethod
          Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
        <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
        <ds:Reference URI="#_ec6adc4fca9e3dc72fff4a1fd99561007777ac7afd">
          <ds:Transforms>
            <ds:Transform
              Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
            <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
          </ds:Transforms>
          <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
          <ds:DigestValue>dxt7OSy1/Xf6+BHgDU4YOi4ogMg=<\/ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>...signature value...<\/ds:SignatureValue>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>...x509 certificate value<\/ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </ds:Signature>
    <saml:Subject>
      <saml:NameID
        Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
        SPNameQualifier="login.identity.cf-app.com">
          [email protected]
      </saml:NameID>
      <saml:SubjectConfirmation
          Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml:SubjectConfirmationData
            InResponseTo="a9e378fia1g38da5503ahgih430fah"
            NotOnOrAfter="2017-05-03T21:56:01Z"
            Recipient="https://..url../saml/SSO/alias/login.identity.cf-app.com" />
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Conditions
        NotBefore="2017-05-03T21:50:31Z"
        NotOnOrAfter="2017-05-03T21:56:01Z">
      <saml:AudienceRestriction>
        <saml:Audience>login.identity.cf-app.com<\/saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement
        AuthnInstant="2017-05-03T21:16:21Z"
        SessionIndex="_a3ab48bcfbb76ad78d4ac28231240af256be171c9f"
        SessionNotOnOrAfter="2017-05-04T05:51:01Z">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>
           urn:oasis:names:tc:SAML:2.0:ac:classes:Password
        </saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
      <saml:Attribute
          Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">
            [email protected]
        </saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="eduPersonAffiliation"
          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">member<\/saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">marissa<\/saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="emailAddress"
          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">
            [email protected]
        </saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

SAML configuration

UAA provides a limited set of attributes to configure when setting up an external IDP. You configure these attributes for each individual SAML IDP you set up in UAA.

A SAML IDP responds to requests from UAA with signed SAML assertions. These signatures are validated using a public key provided by the SAML provider. This public key can be provided as a raw RSA public key or encapsulated in an X.509 certificate. When dealing with the X.509 certificate, as per the SAML V2.0 Metadata Interoperability Profile, UAA will not validate the certificate (including validating its expiry date), but will only get the public key from it.

nameID

The nameID attribute is the element that provides the username in the SAML assertion. This is sometimes called the subject of the assertion. UAA links the external user to the internal shadow user record by matching the nameID to the user.username.

For example:

nameID: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
nameID: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
nameID: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

The most common configuration is unspecified, where the IDP decides which attribute is the username.

The following example is what the subject element looks like in an assertion, with the username [email protected]:

<saml:Subject>
  <saml:NameID
      Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
      SPNameQualifier="login.identity.cf-app.com">
    [email protected]
  </saml:NameID>
  <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    <saml:SubjectConfirmationData InResponseTo="a17j41337a9835i93h78hihc9a89j4b"
      NotOnOrAfter="2017-05-03T21:21:21Z"
      Recipient="https://..url../saml/SSO/alias/login.identity.cf-app.com"
    />
  
 saml:SubjectConfirmation>

 saml:Subject>

AssertionConsumerService

The AssertionConsumerService attribute indicates which assertion consumer service URL the external IDP uses. This is used by the SP when it sends a SAML request for authentication to the IDP. The SP metadata contains one assertion consumer service by default, but can contain more.

The following examples are of assertion consumer services in SP metadata, organized by index:

<md:AssertionConsumerService
  Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  Location="https://login.run.pivotal.io/saml/SSO/alias/login.run.pivotal.io"
  index="0"
  isDefault="true"/>
<md:AssertionConsumerService
  Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
  Location="https://login.run.pivotal.io/saml/SSO/alias/login.run.pivotal.io"
  index="1"/>
<md:AssertionConsumerService
  Binding="urn:oasis:names:tc:SAML:2.0:bindings:URI"
  Location="https://login.run.pivotal.io/oauth/token/alias/login.run.pivotal.io"
  index="2"/>

The following example is a SAML request to the IDP with the correct assertion consumer service selected:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest
    AssertionConsumerServiceURL="https://..../saml/SSO/alias/login.identity.cf-app.com"
    Destination="http://simplesamlphp.identity.cf-app.com/saml2/idp/SSOService.php"
    ForceAuthn="false"
    ID="a17j41337a9835i93h78hihc9a89j4b"
    IsPassive="false"
    IssueInstant="2017-05-03T21:16:15.989Z"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
    Version="2.0"
    xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
  <saml2:Issuer
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
      Login.identity.cf-app.com
  </saml2:Issuer>
  <saml2p:NameIDPolicy
    Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"/>
</saml2p:AuthnRequest>

idpMetadata

The idpMetadata attribute holds either an XML string or an URL.

This is an example of IDP metadata configuration in UAA:

idpMetadata: \http://simplesamlphp.identity.cf-app.com/saml2/idp/metadata.php

If the IDP is configured using a URL, UAA refreshes the metadata content from that URL every 10 minutes. This is useful for providers that rotate their keys frequently.

If the IDP is configured using metadata as an XML string, the metadata remains static. Rotating keys on the IDP requires you to reconfigure UAA with the new data.

This is an example of the XML metadata configuration:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="http://www.okta.com/k2lw4l5bPODCMIIDBRYZ">
  <md:IDPSSODescriptor
      WantAuthnRequestsSigned="true"
      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>..x509 certificate
 ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
 md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
 md:NameIDFormat>
    <md:SingleSignOnService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://s.okta.com/app/env_1/k2lw4l5bPODCMIIDBRYZ/sso/saml" />
    <md:SingleSignOnService
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
        Location="https://s.okta.com/app/env_1/k2lw4l5bPODCMIIDBRYZ/sso/saml" />
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

showSamlLoginLink

The showSamlLoginLink shows the login link on the UAA home page. This appears when showSamlLoginLink is set to true. When you click this link, it starts the SP-initiated flow. This is frequently set to false when you use the IDP-initiated flow.

This is an example of a SAML login link text configuration:

showSamlLoginLink: true

linkText

You can use the linkText attribute to specify the text on a link on the UAA home page. This appears when showSamlLoginLink is set to true.

This is an example of a link text configuration:

linkText: Log in with SSO

metadataTrustCheck

The metadataTrustCheck attribute requires UAA to verify signatures of incoming messages. This requirement exists when metadataTrustCheck is set to true.

This is an example of a metadata trust check configuration:

metadataTrustCheck: true