Identity Providers in UAA

LDAP Providers

The Lightweight Directory Access Protocol communicates with directory servers. In comparison with the other external identity providers, 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:

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

For more information, see the LDAP documentation.

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 identity provider. A mistake on either side will cause assertions 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.

Metadata

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

Download the UAA SP metadata through the /saml/metadata endpoint. Metadata is in XML format. Using this information, you can configure the IDP.

If you use the UAA as an IDP, fetch the metadata from /saml/idp/metadata.

Identity Provider Workflow

SAML provides two commonly-used flows, SP-initiated and IDP-initiated.

SP Initiated

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

The authentication request sent from the SP to the IDP follows:

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>

Once 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. We discuss the SAML response containing the assertion in the next section.

An SP-initiated flow.

IDP Initiated

The user can start their authentication process on the IDP. The IDP sends a SAML assertion to the SP, which in this case is UAA.

An example SAML request with an assertion follows:

<?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">
          marissa@test.org
      </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">
            marissa@test.org
        </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">
            marissa@test.org
        </saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Configuration

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

nameID

The nameID is the element that provides the username in the SAML assertion. We sometimes refer to this as the subject of the assertion. UAA links the external user to the internal shadow user record by matching the nameID to the user.username.

Examples:
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.

An example of what the subject element looks like in an assertion, with the username EXAMPLE@test.org, follows:

<saml:Subject>
  <saml:NameID 
      Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"     
      SPNameQualifier="login.identity.cf-app.com">
    EXAMPLE@test.org
  </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>

assertion Consumer Service

Indicates which assertion consumer service URL the external identity provider should use. This is used by the SP when it sends a SAML request for authentication to the IDP. The SP metadata contains one or more assertion consumer services. One is the default.

An example assertion consumer services in SP metadata, organized by index, follows:

<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"/>

An example SAML request to the IDP with the correct assertion consumer service selected follows:

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

This attribute holds either an XML string or a URL.

An example IDP metadata configuration in UAA follows:

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

If the IDP is configured using a URL, UAA will refresh 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 will require UAA to be reconfigured with the new data.

An example of the XML metadata configuration follows:

<?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 certificateds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddressmd:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecifiedmd: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>

linkText

The link text allows you to specify the text on a link on the UAA home page. Shows when showSamlLoginLink is set to true.

An example link text configuration follows:

linkText: Login in with SSO

Set to true to display the login link on the UAA home page. Clicking on this link starts the SP initiated flow. This is frequently set to false when you use the IDP initiated flow.

An example link text configuration follows:

showSamlLoginLink: true

metadataTrustCheck

Set to true if you wish the UAA to verify signatures of incoming messages.

Create a pull request or raise an issue on the source for this page in GitHub