Configure UAA in CF with SAML as A Service Provider

Before we start going through how to configure UAA in CF with SAML as a Service Provider, let’s make sure we have common terminology.

UAA

The User Account and Authentication (UAA) is the OAuth2 server used as the identity management service for Cloud Foundry (CF).

UAA supports standard protocols such as the Security Assertion Markup Language (SAML) and Lightweight Directory Access Protocol (LDAP) to provide Single Sign-On (SSO) service.

SAML

SAML is an XML-based, open-standard data format for exchanging authentication and authorization data between an Service Provider (SP) and an Identity Provider (IDP).

The SP trusts the IDP to authenticate users and IDP generates an authentication assertion which is sent to SP to indicate that a user has been authenticated.

A common case is that setting Active Directory Federation Services (ADFS) as an IDP and SAML as a single-sign-on (SSO) SP.

SAML Integration on UAA

UAA can be configured as either an SP or IDP. Typically, UAA is the SP, and an external provider, such as Okta or [Active Directory Federation Services (ADFS)] (https://msdn.microsoft.com/en-us/library/bb897402.aspx), is the IDP.

We must configure both UAA SP and the external SAML IDP when we set SAML integration on UAA. A misconfigure on either side will cause authentication to fail.

Now we have the basic concepts defined, next we will walk you through how to configure UAA in CF with SAML as an SP.

Configure UAA in CF with SAML as An SP

Configure IDP
First, obtain the UAA SP metadata from the following endpoint and save it into a file.

https://login.YOUR-CF-SYSTEM-DOMAIN/saml/metadata

Next, import this SAML SP configure to your external IDP. Different IDPs have different instructions on how to import SP metadata, thus we will skip the details for this step.

Configure UAA SP

First, obtain the IDP metadata from your external IDP provider.

Next, we will configure UAA SP in the CF manifest and redeploy CF to make the UAA SP configuration take effect. No matter how you manage your CF manifest/deployments, the following configuration is needed for your CF manifest.

Note that the key/cert are usually generated automatically as part of CF manifest with the same root CA used by uaa.

name: uaa
jobs:
- name: uaa
  properties:
    login:
      saml:
        # Provider Information Configs
        providers:
          # Example
          myPvovider:
            nameID: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
            idpMetadata: the matadata itself or the link to it
            showSamlLoginLink: true
            linkText: Log in with XX IDP
            metadataTrustCheck: false
        #The active key is used for signing messages and the key to be used to encrypt messages.
        activeKeyId: key1
        keys:
          key1:
            key: #uaa login saml key
            certificate: # uaa login saml certificate
            passphrase: ""
          # you can add multiple keys such as key1, key2...

After you complete configurations on both sides, you can go ahead to verify your SAML integration with UAA in CF work.