LATEST VERSION: 1.5 - CHANGELOG
Single Sign-On v1.4

Configure Identity Providers

This topic describes how Pivotal Cloud Foundry (PCF) administrators configure a Single Sign-On (SSO) service plan to manage user access to PCF apps, for users with accounts in the internal user store or with external identity providers.

Configure Internal User Store

  1. Log in to the SSO dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your User Account and Authentication (UAA) administrator credentials. Find these credentials in your Pivotal Elastic Runtime tile in Ops Manager under the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the drop-down menu.

  3. Click Internal User Store and select Edit Provider from the drop-down menu.

  4. (Optional) Under Authentication Policy select one of the following:

    • Disable Internal Authentication: This option prevents authentication against the internal user store. You must have at least one external identity provider configured.

      Note: The login page does not include the Email and Password fields if you select this option.

    • Disable User Management: This option prevents all users, including administrators, from performing actions on internal users.

      Note: The login page does not include Create Account and Reset Password links if you select this option.

  5. Under Password Policy Settings, select Use Recommended Settings, Use Default Settings, or enter custom settings in the fields below.

  6. Click Save Identity Provider.

Add Internal Users From the Command Line

You can use the Internal Users admin pane to send invitations to users, so that they can add themselves to the internal user store. But you cannot use the admin pane to add users directly.

To create new internal user accounts directly, supplying the user’s name, email address and other info, use the UAA Command Line Interface (UAAC) as follows:

  1. If you do not already have the UAAC installed, run gem install cf-uaac in a terminal window.

  2. Create an admin client that can manage users in the Service Plan. Include the following scopes for the client:

    • clients.admin
    • scim.read
    • scim.write
  3. Record the App ID and App Secret. These are used as your client ID and client secret.

  4. Target the auth domain of your SSO service plan. This is the URL you provided when creating a Service Plan in the SSO dashboard.

    $ uaac target https://YOUR-AUTH-DOMAIN.login.YOUR-SYSTEM-DOMAIN

  5. Fetch the App ID token for the admin client created above.

    $ uaac token client get ADMIN-CLIENT-ID
    Client secret:
    

  6. When prompted with Client secret, enter the App Secret admin client secret recorded above.

  7. Add new users by providing the user’s email address, username, and password.

    $ uaac user add --emails YOUR-USER@EMAIL.COM
    User name:  YOUR-USER
    Password:  ****
    Verify password:  ****
    user account successfully added

  8. (Optional) You can also create groups and add users to them.

    $ uaac group add
    Group name:  YOUR-GROUP
    meta
    version: 0
    created: 2016-02-19T23:17:17.000Z
    lastmodified: 2016-02-19T23:17:17.000Z
    schemas: urn:scim:schemas:core:1.0
    id: 8725b5fd-8da2-4cfc-89b1-c57048f089c2
    displayname: YOUR-GROUP
    
    To add a member to your new group, use the following command.
    $ uaac member add YOUR-GROUP YOUR-USER

Define Password Policy for the Internal User Store

Administrators can define the password policy for SSO users in the internal user store. The password policy enforces rules that restrict the kinds of passwords users can create.

  1. Log in to the SSO dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA administrator credentials. You can find these credentials in your Pivotal Elastic Runtime tile in Ops Manager under the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the drop-down menu.

  3. Click Internal User Store and select Edit Provider from the drop-down menu.

  4. Configure the following under the Password Complexity section:

    • Min Length: Specify the minimum password length.
    • Uppercase: Specify the minimum number of uppercase characters required in a password.
    • Lowercase: Specify the minimum number of lowercase characters required in a password.
    • Special Characters: Specify the minimum number of special characters required in a password.
    • Numerals: Specify the minimum number of numeric characters required in a password.
  5. Configure the following under the Lockout Policy section:

    • Failures Allowed: Specify the number of failed login attempts allowed per hour before a user is locked out.
    • Lockout Period: Specify the number of seconds a user is locked out for after excessive failed login attempts.
    • Password Expires: Specify the number of months passwords are valid for before users needs to enter a new password.
  6. Click Save Identity Provider.

Configure Service Provider SAML Settings

For each plan, the Single Sign-On service allows you to configure SAML settings when SAML is used for exchanging authentication and authorization data between the identity provider and the service provider. The SSO service provides the ability to sign authentication requests and require signed assertions from the external identity provider.

  1. Log in to the SSO dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA administrator credentials. You can find these credentials in your Pivotal Elastic Runtime tile in Ops Manager under the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the drop-down menu.

  3. Click Configure SAML Service Provider.

  4. Configure the following settings:

    • Perform signed authentication requests: The service provider signs requests sent to the external identity provider.
    • Require signed assertions: The service provider requires that responses from the external identity provider are signed.
  5. Click Save to save the configurations.

  6. Click Download Metadata.

Add an External Identity Provider

See the following sets of instructions for how to configure the SSO service to use external identity providers that support SAML 2.0, OpenID Connect (OIDC), and LDAP.

Add a SAML Provider

  1. Log in to the SSO dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA administrator credentials. You can find these credentials in your Pivotal Elastic Runtime tile in Ops Manager under the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the drop-down menu.

  3. Click New Identity Provider.

  4. Enter an Identity Provider Name.

  5. Select SAML 2.0 as the Identity Provider Type.

  6. Enter a Description. This is displayed to Space Developers when they select an identity provider for their app.

  7. Enter the external identity provider metadata in one of the following ways:

    • Option 1: Provide the Identity Provider Metadata URL and click Fetch Metadata.
    • Option 2: Click Upload Identity Provider Metadata to upload XML metadata that you downloaded from your external identity provider.

      Note: If you choose to upload the Identity Provider Metadata as an XML file, you will be unable to use the Fetch Metadata option to update your Identity Provider metadata later. If metadata changes on the Identity Provider side, you will have to manually re-upload them as an updated XML file.

  8. Configure any User Attributes to propagate from the identity provider to the service provider. These attributes can include email addresses, first or last names, or external groups. They are sent to apps via OpenID tokens, along with any other stored user information issued by the Single Sign-On service.

    • Select a User Scheme Attribute from the drop-down menu.
    • Enter a SAML Attribute Name with the corresponding attribute from the incoming SAML assertion.
  9. Configure any Custom Attributes to propagate from the identity provider to the service provider. These attributes are sent to apps via OpenID tokens issued by the Single Sign-On service.

    • Enter a Custom Attribute Name.
    • Enter a SAML Attribute Name with the corresponding attribute from the incoming SAML assertion.
  10. (Optional) Check Persist Custom Attributes if you want to expose custom user attributes through the /userinfo endpoint. Your app must also have the user_attributes scope assigned in order for the custom attributes to appear.

  11. 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 on Configure SAML Service Provider on the Identity Providers page.

Add an OIDC Provider

  1. Log in to the SSO dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA administrator credentials. You can find these credentials in your Pivotal Elastic Runtime tile in Ops Manager under the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the drop-down menu.

  3. Click New Identity Provider.

  4. Enter an Identity Provider Name.

  5. Enter a Description. This is displayed to Space Developers when they select an identity provider for their app.

  6. Select OpenID Connect as the Identity Provider Type.

  7. Enter the external OpenID Connect (OIDC) identity provider metadata in one of the following ways:

    • Option 1: Select the Enable Discovery checkbox, provide the Discovery Endpoint URL, Relying Party OAuth Client ID, and Relying Party OAuth Client Secret and click Fetch Scopes.
    • Option 2: Clear the Enable Discovery checkbox and provide the Authorization Endpoint URL, Token Endpoint URL, Token Key (URL), Relying Party OAuth Client ID, and Relying Party OAuth Client Secret.
  8. Select the applicable Scopes for the OIDC identity provider.

  9. Configure any User Attributes to propagate from the identity provider to the service provider. These attributes can include email addresses, first or last names, or external groups. They are sent to apps via OpenID tokens, along with any other stored user information issued by the Single Sign-On service.

    • Select a User Scheme Attribute from the drop-down menu.
    • Enter an ID Token Attribute Name with the corresponding attribute from the incoming OIDC ID token.
  10. Configure any Custom Attributes to propagate from the identity provider to the service provider. These attributes are sent to apps via OpenID tokens issued by the Single Sign-On service.

    • Enter a Custom Attribute Name.
    • Enter an ID Token Attribute Name with the corresponding attribute from the incoming OIDC ID token.
  11. (Optional) Check Persist Custom Attributes if you want to expose custom user attributes through the /userinfo endpoint. Your app must also have the user_attributes scope assigned in order for the custom attributes to appear.

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

Add an LDAP Identity Provider

When integrating with an external identity provider for LDAP, authentication becomes chained. An authentication attempt with a user’s 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 directly. You may only have one LDAP external identity provider per service plan.

  1. Log in to the SSO dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA administrator credentials. You can find these credentials in your Pivotal Elastic Runtime tile in Ops Manager under the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the drop-down menu.

  3. Click New Identity Provider.

  4. Enter an Identity Provider Name.

  5. Enter a Description. This is displayed to Space Developers when they select an identity provider for their app.

  6. Select LDAP as the Identity Provider Type. You may only have one LDAP provider per Service Plan.

  7. Enter the external LDAP identity provider configurations:

    1. Enter the Hostname and Port.
    2. Select the applicable Security protocol.
    3. Select the applicable Referral.
    4. Enter the User DN and Bind Password for your LDAP service account.
    5. Under the Users section, enter the Search Base.
    6. Under the Users section, you may also enter in Search Filter (Optional).
    7. Under the Users section, you may select Just in Time Provisioning. If this option is enabled, users will be created at login time. If this option is not enabled, users must be created prior to being able to login.
    8. Under the Groups section, you may enter in enter the Search Base (optional) and Search Filter (optional) in order to associate LDAP groups with your user. If you wish to use the memberOf attribute on user objects, you can enter in the value memberOf as the Search Base instead of an LDAP path for a group OU, and the Search Filter value will be ignored.
  8. Configure any User Attributes to propagate from the identity provider to the service provider. These attributes can include email addresses, first or last names, or external groups. They are sent to apps via OpenID tokens, along with any other stored user information issued by the Single Sign-On service.

    • Select a User Scheme Attribute from the drop-down menu.
    • Enter an LDAP Attribute Name with the corresponding attribute from LDAP.
  9. Configure any Custom Attributes to propagate from the identity provider to the service provider. These attributes are sent to apps via OpenID tokens issued by the Single Sign-On service.

    • Enter a Custom Attribute Name.
    • Enter an LDAP Attribute Name with the corresponding attribute from LDAP.
  10. (Optional) Check Persist Custom Attributes if you want to expose custom user attributes through the /userinfo endpoint. Your app must also have the user_attributes scope assigned in order for the custom attributes to appear.

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

Delete an External Identity Provider

  1. Log in to the SSO dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA administrator credentials. You can find these credentials in your Pivotal Elastic Runtime tile in Ops Manager under the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the drop-down menu.

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

  4. Click Delete at the bottom of the page.

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

Note: Deleting an external identity provider deletes all of its configurations. Users will no longer be able to authenticate using the external identity provider. This action cannot be undone.

Configure Group Whitelist for an External Identity Provider

An administrator 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 through an external identity provider. An app can then retrieve from the ID token the list of external groups that the user belongs to. An administrator can use these groups to assign permissions by group rather than individual users.

For more details on how to create resource permission mappings, see Create or Edit Resource Permissions.

Note: For an app to retrieve a Group Whitelist containing external groups, the app must request the roles scope, and the Group Whitelist must list the external group.

  1. Log in to the SSO dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA administrator credentials. You can find these credentials in your Pivotal Elastic Runtime tile in Ops Manager under the Credentials tab.

  2. Click the plan name and select Manage Identity Providers from the drop-down menu.

  3. Click on the name of your external identity provider and select Group Whitelist from the drop-down menu.

  4. Add a group name from your external identity provider.

  5. Click Save Group Whitelist.

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