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 also 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 specification defines two players in a SAML 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 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 ADFS, 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 and IDP-initiated. These sections describe each workflow.

SP-Initiated

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, like the example below:

<?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.

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.

Below is an example of 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 should use. 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.

Below are examples 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"/>

Below is an example of 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 a URL.

Below 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.

Below 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.

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

showSamlLoginLink: true

linkText

The linkText attribute allows you to specify the text on a link on the UAA home page. This shows when showSamlLoginLink is set to true.

Below 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.

Below is an example of a metadata trust check configuration:

metadataTrustCheck: true