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 (IdP).

Note: You can also configure a 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 Single Sign‑On to use external IdPs that support:

To delete an external IdP, see Delete an External Identity Provider below.

Add a SAML Provider

To add an external SAML IdP:

  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 Pivotal Application Service 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 IdP authenticates. This description is displayed to the Space Developers when they select an IdP 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 IdP Metadata configurations

    Field Instructions
    Identity Provider Metadata URL Enter a Identity Provider Metadata URL and click Fetch Metadata. If you select this option, your metadata is periodically fetched from the configured URL. This keeps the metadata up-to-date.
    SAML File Metadata Click Upload Identity Provider Metadata and upload the XML metadata that you downloaded from your external IdP. If you select this option, your metadata is not periodically updated. If the metadata changes, you must manually upload the file again.
  8. Enter Email Domains. This is a comma-separated list of domains for IdP 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 IdP 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 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 IdP to the service provider.
    They are sent to apps through OpenID tokens, along with any other stored user information issued by Single Sign‑On.
    1. (Optional) 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 IdP.

  11. (Optional) Configure the service provider SAML settings for signing authentication requests and incoming assertions, by following the procedure in Configure SAML Settings below.

  12. (Optional) Transfer group memberships and roles from existing SAML groups to Single Sign‑On by following the procedures in Create or Edit Resource Permissions Mapping and Configure Group Whitelist for an External Identity Provider below.

Configure SAML Settings

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

Single Sign‑On enables the ability to sign authentication requests and require signed assertions from the external IdP.

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 PAS 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 IdP.
    Require signed assertions Select this checkbox to enable the service provider to require that responses from the external IdP are signed

  5. Click Save to save the configurations.

  6. Click Download Metadata.

Add an OIDC Provider

To add a external OIDC IdP:

  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 PAS 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 IdP authenticates. This description is displayed to the Space Developers when they select an IdP 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 IdP metadata.
      Relying Party OAuth Client ID Enter the client ID from the IdP.
      Relying Party OAuth Client Secret Enter the client secret from the IdP.

    4. Click Fetch Scopes.
    5. Select the applicable Scopes for your IdP
    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 IdP metadata.
      Token Endpoint URL Enter the token endpoint URL from the IdP metadata.
      Token Key Enter the token key URL value from the IdP metadata.
      Issuer (Optional) If this field is required by your IdP, enter a value.
      User Info Endpoint URL (Optional) If this field is required by your IdP, enter a value.
      Response Type If this field is required by your IdP, select a value.
      Relying Party OAuth Client ID Enter the client ID from the IdP.
      Relying Party OAuth Client Secret Enter the client secret from the IdP.

    4. Select the applicable Scopes for your IdP
  8. Enter Email Domains. This is a comma-separated list of domains for IdP 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 IdP 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 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 IdP to the service provider.
    They are sent to apps through OpenID tokens, along with any other stored user information issued by Single Sign‑On.
    1. (Optional) 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 IdP.

  11. (Optional) Transfer group memberships and roles from existing OIDC groups to Single Sign‑On by following the procedures in Create or Edit Resource Permissions Mapping and Configure Group Whitelist for an External Identity Provider below.

Add an LDAP Provider

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

When using an LDAP external IdP, you should not:

  • Bootstrap or Create Users in the UAA Database: This can cause user collisions.
  • Enable Manual Lockouts: For example, lockouts that result from users using the same account.
  • Enable Automated Deletions: This can disrupt service accounts and prevent user logins.

VMware recommends that you do not reuse LDAP service accounts across environments. You can only have one LDAP external IdP per service plan.

To add a LDAP IdP:

  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 Pivotal Application Service 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 IdP authenticates. This description is displayed to the Space Developers when they select an IdP 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.
    To use the memberOf attribute on user objects, enter the value memberOf as the Search Base instead of an LDAP path for a group organizational unit. This causes 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 IdP 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 IdP to the service provider.
    They are sent to apps through OpenID tokens, along with any other stored user information issued by 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 IdP to the service provider.
    They are sent to apps through OpenID tokens, along with any other stored user information issued by Single Sign‑On.
    1. (Optional) 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 IdP.

  11. (Optional) Transfer group memberships and roles from existing SAML groups to Single Sign‑On by following the procedures in Create or Edit Resource Permissions Mapping and Configure Group Whitelist for an External Identity Provider below.

Delete an External Identity Provider

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

To delete an external IdP:

  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 PAS 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 IdP.

  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 IdP, along with all of its configurations.

Transfer 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 IdP groups to 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 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 PAS 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 IdP you want to define permissions for and select Resource Permissions from the dropdown.

  4. Click New Permissions Mapping.

  5. Enter a Group Name. The group name depends on the IdP you are configuring:

    • SAML or OIDC providers: Enter the group name that you defined in the external IdP.
    • LDAP providers: Enter the fully qualified LDAP paths. The path uses this 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 PAS 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 IdP 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 IdP in a group whitelist. The list of groups in the whitelist propagates in the ID token when a user authenticates using an external IdP.

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 PAS 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 IdP and select Group Whitelist from the dropdown.

  4. Enter a group name from your external IdP. 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 IdP configurations.

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