Configuring External Identity Providers

This topic describes how Pivotal Platform admins configure a Pivotal Single Sign‑On service plan to manage user access to Pivotal Platform apps using an external identity provider.

Note: You can also configure a Pivotal Single Sign‑On service plan to use the internal user store to manage user accounts. For more information, see Configuring Internal User Store.

Configure an External Identity Provider

You can configure Pivotal Single Sign‑On to use external identity providers that support:

To delete an external identity provider, see Delete an External Identity Provider.

Add a SAML Provider

To add an external SAML identity provider:

  1. Log in to the SSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA admin credentials. You can find these credentials in your tile in Ops Manager on the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the dropdown.

  3. Click New Identity Provider.

  4. Enter an Identity Provider Name. This name is displayed as a link on the login page.

  5. Enter an Identity Provider Description. This is the name of the group that the identity provider authenticates. This description is displayed to the Space Developers when they select an identity provider for their app.

  6. Under Identity Provider type, select SAML 2.0.

  7. Configure Identity Provider Metadata by configuring one of the below fields as follows:

    SAML Identity Provider Metadata configurations

    Field Instructions
    Identity Provider Metadata URL Enter a Identity Provider Metadata URL and click Fetch Metadata.
    SAML File Metadata Click Upload Identity Provider Metadata and upload the XML metadata that you downloaded from your external identity provider.

    Note: Uploading a XML metadata file disables entering a metadata URL to update your identity provider metadata later. If your metadata changes in your identity provider, you must manually re-upload the metadata as an updated XML file.

  8. Enter Email Domains. This is a comma-separated list of domains for identity provider discovery.

  9. (Optional) Under Advanced Settings, click Attribute Mappings and configure the fields as follows: Attribute Mappings fields

    Field Instructions
    User Attributes Enter any user attributes to propagate from the identity provider to the service provider.
    These attributes can include email addresses, first names, last names, or external groups. They are sent to apps through OpenID tokens, along with any other stored user information issued by Pivotal Single Sign‑On.
    1. Select a User Scheme Attribute from the dropdown.
    2. Enter a SAML Attribute Name with the corresponding attribute from the incoming SAML assertion.
    Custom Attributes Enter any custom attributes to propagate from the identity provider to the service provider.
    They are sent to apps through OpenID tokens, along with any other stored user information issued by Pivotal Single Sign‑On.
    1. (Optional) If you want to expose custom user attributes through the /userinfo endpoint, select Persist Custom Attributes. Your app must also have the user_attributes scope assigned for the custom attributes to appear.
    2. Enter a Custom Attribute Name.
    3. Enter a SAML Attribute Name with the corresponding attribute from the incoming SAML assertion.

  10. Click Create Identity Provider to save the identity provider.

Note: To configure the service provider SAML settings, such as the signing of authentication requests and incoming assertions, click Configure SAML Service Provider on the Identity Providers page. For more information, see Configure SAML Settings below.

Configure SAML Settings

For each plan, you can configure SAML settings when SAML is used for exchanging authentication and authorization data between the identity provider and the service provider.

Pivotal Single Sign‑On provides the ability to sign authentication requests and require signed assertions from the external identity provider.

To configure SAML settings:

  1. Log in to the SSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA admin credentials. You can find these credentials in your tile in Ops Manager under the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the dropdown.

  3. Click Configure SAML Service Provider.

  4. Configure the fields as follows:

    Field Description
    Perform signed authentication requests Select this checkbox to enable the service provider to sign requests sent to the external identity provider.
    Require signed assertions Select this checkbox to enable the service provider to require that responses from the external identity provider are signed

  5. Click Save to save the configurations.

  6. Click Download Metadata.

Add an OIDC Provider

To add a external OIDC identity provider:

  1. Log in to the SSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA admin credentials. You can find these credentials in your tile in Ops Manager on the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the dropdown.

  3. Click New Identity Provider.

  4. Enter an Identity Provider Name. This name must match your origin key. However, you can replace lowercase letters with capital letters and replace dashes with spaces. This name is displayed as a link on the login page.

  5. Enter an Identity Provider Description. This is the name of the group that the identity provider authenticates. This description is displayed to the Space Developers when they select an identity provider for their app.

  6. Under Identity Provider type, select OpenID Connect.

  7. Configure OpenID Connect Settings by configuring one of the below fields as follows:
    The tabs below expand to show instructions for each type of endpoint URL.

    Pane for configuring a Discovery Endpoint URL.
    1. (Optional) If you do not want to use SSL validation, select Skip SSL Validation.
    2. Ensure the Enable Discovery checkbox selected.
    3. Configure the fields as follows:
      Field Instructions
      Discovery Endpoint URL Enter the discovery endpoint URL from the identity provider metadata.
      Relying Party OAuth Client ID Enter the client ID from the identity provider.
      Relying Party OAuth Client Secret Enter the client secret from the identity provider.

    4. Click Fetch Scopes.
    5. Select the applicable Scopes for your identity provider
    Pane for configuring a Authorization Endpoint URL.
    1. (Optional) If you do not want to use SSL validation, select Skip SSL Validation.
    2. Deselect the Enable Discovery checkbox.
    3. Configure the fields as follows:
      Field Description
      Authorization Endpoint URL Enter the authorization endpoint URL from the identity provider metadata.
      Token Endpoint URL Enter the token endpoint URL from the identity provider metadata.
      Token Key Enter the token key URL value from the identity provider metadata.
      Issuer (Optional) If this field is required by your identity provider, enter a value.
      User Info Endpoint URL (Optional) If this field is required by your identity provider, enter a value.
      Response Type If this field is required by your identity provider, select a value.
      Relying Party OAuth Client ID Enter the client ID from the identity provider.
      Relying Party OAuth Client Secret Enter the client secret from the identity provider.

    4. Select the applicable Scopes for your identity provider
  8. Enter Email Domains. This is a comma-separated list of domains for identity provider discovery.

  9. (Optional) Under Advanced Settings, click Attribute Mappings and configure the fields as follows: Attribute Mappings fields

    Field Instructions
    User Attributes Enter any user attributes to propagate from the identity provider to the service provider.
    These attributes can include email addresses, first names, last names, or external groups. They are sent to apps through OpenID tokens, along with any other stored user information issued by Pivotal Single Sign‑On.
    1. Select a User Scheme Attributefrom the dropdown.
    2. Enter a ID Token Attribute Name with the corresponding attribute from the incoming OIDC ID token
    Custom Attributes Enter any custom attributes to propagate from the identity provider to the service provider.
    They are sent to apps through OpenID tokens, along with any other stored user information issued by Pivotal Single Sign‑On.
    1. (Optional) If you want to expose custom user attributes through the /userinfo endpoint, select Persist Custom Attributes. Your app must also have the user_attributes scope assigned for the custom attributes to appear.
    2. Enter a Custom Attribute Name.
    3. Enter a ID Token Attribute Name with the corresponding attribute from the incoming OIDC ID token.

  10. Click Create Identity Provider to save the identity provider.

Add an LDAP Identity Provider

When integrating Pivotal Single Sign‑On with a LDAP external identity provider, authentication is chained. An authentication attempt with user credentials is first attempted against the internal user store before the external LDAP identity provider.

To avoid username collision, do not bootstrap or create users in the UAA database directly. You can only have one LDAP external identity provider per service plan.

Warning: Pivotal recommends that you do not reuse LDAP service accounts across environments. LDAP service accounts should not be subject to manual lockouts, such as lockouts that result from users using the same account. LDAP service accounts should not be subject to automated deletions as disruption to these service accounts could prevent user logins.

To add a LDAP identity provider:

  1. Log in to the SSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA admin credentials. You can find these credentials in your tile in Ops Manager on the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the dropdown.

  3. Click New Identity Provider.

  4. Enter an Identity Provider Name. This name is displayed as a link on the login page.

  5. Enter an Identity Provider Description. This is the name of the group that the identity provider authenticates. This description is displayed to the Space Developers when they select an identity provider for their app.

  6. Under Identity Provider type, select LDAP. You can only have one LDAP provider per Service Plan.

  7. Configure the fields as follows: Fields for configuring a connection to a LDAP IdP

    Field Instructions
    Connection
    Hostname Enter the hostname for your LDAP server.
    Port Enter the post name for your LDAP server.
    Security protocol Select the security protocol that your LDAP uses for connection.
    Referral Select how UAA handles LDAP server referrals to other user stores.
    User DN Enter the LDAP Distinguished Name (DN) for binding to your LDAP server.
    Bind Password Enter the password for binding to your LDAP server.
    Users
    Search Base Enter the location in the LDAP directory tree where LDAP user search begins. The LDAP search base typically matches your domain name.
    Search Filter (Optional) Enter a string to use for LDAP user search criteria.
    Just in Time Provisioning If this option is enabled, users are created at login time.
    If this option is not enabled, users must be created before being able to log in
    Groups
    Search Base (Optional) Enter the location in the LDAP directory tree where the LDAP group search begins.
    If you want to use the memberOf attribute on user objects, you can enter the value memberOf as the Search Base instead of an LDAP path for a group organizational unit. This causes Pivotal Single Sign‑On to ignore the Search Filter value.
    Search filter (Optional) Enter a string that defines LDAP group search criteria. The standard value is member={0}.

  8. Enter Email Domains. This is a comma-separated list of domains for identity provider discovery.

  9. (Optional) Under Advanced Settings, click Attribute Mappings and configure the fields as follows: Attribute Mappings fields

    Field Instructions
    User Attributes Enter any user attributes to propagate from the identity provider to the service provider.
    They are sent to apps through OpenID tokens, along with any other stored user information issued by Pivotal Single Sign‑On.

    The only configurable attributes for LDAP are given_name, family_name, and phone_number. Configuring email and external_groups has no effect on your LDAP integration.
    1. Select a User Scheme Attribute from the dropdown.
    2. Enter a LDAP Attribute Name with the corresponding attribute LDAP.
    Custom Attributes Enter any custom attributes to propagate from the identity provider to the service provider.
    They are sent to apps through OpenID tokens, along with any other stored user information issued by Pivotal Single Sign‑On.
    1. (Optional) If you want to expose custom user attributes through the /userinfo endpoint, select Persist Custom Attributes. Your app must also have the user_attributes scope assigned for the custom attributes to appear.
    2. Enter a Custom Attribute Name.
    3. Enter a LDAP Attribute Name with the corresponding attribute from LDAP.

  10. Click Create Identity Provider to save the identity provider.

  11. (Optional) Transfer group memberships and roles from existing LDAP groups to Pivotal Single Sign‑On as follows:

    1. Map existing LDAP user group memberships to Pivotal Single Sign‑On resources by creating a permissions mapping for your LDAP identity provider. See Create or Edit Resource Permissions Mapping below.
    2. Propagate the existing LDAP user group memberships into the roles claim of the OpenID tokens issued by Pivotal Single Sign‑On. See Configure Group Whitelist for an External Identity Provider below.

Delete an External Identity Provider

Note: Deleting an external identity provider deletes all of its configurations. This prevents users from authenticating through the external identity provider. You cannot undo this action.

To delete an external identity provider:

  1. Log in to the SSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA admin credentials. You can find these credentials in your tile in Ops Manager on the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the dropdown.

  3. Click on the name of your external identity provider.

  4. Click Delete at the bottom of the page.

  5. In the dialog box that appears, click Delete Identity Provider to confirm that you want to delete the identity provider, along with all of its configurations.

Transfer LDAP Group Membership and Roles

You can use the SSO Operator Dashboard to configure resource permissions mappings and group whitelists to transfer group membership and roles from existing LDAP groups to Pivotal Single Sign‑On.

SSO Operator Dashboard enables you to:

Create or Edit Resource Permissions Mapping

After a Space Developer defines the resources required by an app, an admin can map existing groups to those resources. For information about how Space Developers define resources, see Create or Edit Resources.

After resource permissions mappings are configured and a user authenticates, the user’s group memberships are mapped to scopes in the resulting token.

To create or edit resource permissions mappings:

  1. Log in to the SSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA admin credentials. You can find these credentials in your tile in Ops Manager on the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the dropdown.

  3. Click the name of the external identity provider you want to define permissions for and select Resource Permissions from the dropdown.

  4. Click New Permissions Mapping.

  5. Enter a Group Name. You must enter fully qualified LDAP paths, using the format cn=XXX-group,ou=users,o=YYY,dc=ZZZ,dc=com.

  6. Click Select Permissions and select the permissions that users in the group should have access to.

  7. Click Save Permissions Mapping.

Note: Groups with unsupported characters in Permission Mappings are not editable.

Note: You can use the UAA API to automate the above procedure. To do this automation, you need an identity zone admin client. For instructions about creating the identity zone admin client, see Create a UAA Identity Zone Admin Client.

For instructions about granting admin permissions to mapped external identity groups, see Grant Admin Permissions to an External Group (SAML or LDAP) in the Cloud Foundry documentation.

Delete Resource Permissions Mapping

To delete a resource permissions mapping:

  1. Log in to the SSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA admin credentials. You can find these credentials in your tile in Ops Manager on the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the dropdown.

  3. Click on the name of the external identity provider you want to delete permissions for and select Resource Permissions from the dropdown.

  4. Click the group name of the resource permission you want to delete.

  5. Click Delete at the bottom of the page.

  6. On the dialog box, click Delete Permissions Mapping to delete the resource.

Note: Groups with unsupported characters in Permission Mappings are not editable.

Note: You can use the UAA API to automate the above procedure. To do this automation, you need an identity zone admin client. For instructions about creating the identity zone admin client, see Create a UAA Identity Zone Admin Client.

For information about un-mapping a group mapping, see Unmap in the UAA API documentation.

Configure Group Whitelist for an External Identity Provider

An admin can include groups from an external identity provider in a group whitelist. The list of groups in the whitelist propagates in the ID token when a user authenticates using an external identity provider.

An app can retrieve from the ID token the list of external groups that the user belongs to. An admin can use these groups to assign permissions by group rather than by individual users.

For information about how to create resource permission mappings, see Create or Edit Resource Permissions Mapping above.

Note: For an app to retrieve an ID token or a /userinfo response containing external groups, the app must request the roles claim and the group whitelist must include the external groups.

To configure a group whitelist:

  1. Log in to the SSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA admin credentials. You can find these credentials in your tile in Ops Manager on the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the dropdown.

  3. Click on the name of your external identity provider and select Group Whitelist from the dropdown.

  4. Enter a group name from your external identity provider. You can use a regex to add group names. For example, you can use * to refer to all groups.

  5. Click the + icon.

  6. Click Save Group Whitelist.

Test Identity Provider Configurations

Pivotal provides sample apps you can deploy to validate your identity provider configurations.

To deploy a sample app, see identity-sample-apps in GitHub.