Configuring Authentication and Enterprise SSO for PAS

Page last updated:

This topic describes Pivotal Application Service (PAS) authentication and single sign-on configuration with Lightweight Directory Access Protocol (LDAP) and Security Assertion Markup Language (SAML).

Overview

Connecting PAS to either the LDAP or SAML external user store allows the User Account and Authentication (UAA) server to delegate authentication to existing enterprise user stores.

If your enterprise user store is exposed as a SAML or LDAP Identity Provider for single sign-on (SSO), you can configure SSO to allow users to access the Apps Manager and Cloud Foundry Command Line Interface (cf CLI) without creating a new account or, if using SAML, without re-entering credentials.

For information about managing user identity and pre-provisioning user roles with SAML or LDAP, see Adding Existing SAML or LDAP Users to a Pivotal Platform Deployment.

For an explanation of the process used by the UAA Server when it attempts to authenticate a user through LDAP, see Configuring LDAP Integration with Pivotal Platform in the Pivotal Knowledge Base.

Note: When integrating with an external identity provider, such as LDAP, authentication within the UAA becomes chained. An authentication attempt with a user’s credentials is first attempted against the UAA user store before the external provider, LDAP. For more information, see Chained Authentication in the User Account and Authentication LDAP Integration GitHub documentation.

Follow one of the procedures below to configure your deployment with SAML or LDAP.

Configure PAS to Use a SAML Identity Provider

In SAML terminology, the SAML protocol communicates user data between an identity provider and a service provider.

To connect PAS with SAML, follow both of these procedures:

Configure PAS as a Service Provider for SAML

To configure PAS to use a SAML identity provider:

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click the Pivotal Application Service tile.

  3. Select the Domains pane and record your system domain. The page header says 'Domains'. Below this header is the text 'For help configuring these fields, see the Configure Domains section of the Configuring PAS topic in the PCF documentation,' with 'Configure Domain' in blue letters to denote a clickable link. Below this text are two fields labeled 'System domain' and 'Apps domain', with red asterisks to denote that they are required fields. The 'System domain' field contains the ghost text 'system.example.com'. The 'Apps domain' field contains the ghost text 'apps.example.com'. At the bottom of the image is a rectangular blue button labeled 'Save'.

  4. Select the Authentication and Enterprise SSO pane.

  5. Select SAML identity provider. At the top of the image is the text 'Configure your UAA user account store with either internal or external authentication mechanisms:', with a red asterisk to denote that it is a required field. Below this text is a radio button labeled 'Internal UAA' and a selected radio button labeled 'SAML identity provider'. Below the 'SAML identity provider' button are two fields with red asterisks labeled 'Provider name' and 'Display name'. Next is a text area labeled 'Provider metadata'. Next is a field labeled 'Provider metadata URL'. Next is a dropdown labeled 'Name ID format', with a red asterisk, with the 'Email Address' option selected. Next are five fields labeled, from top to bottom: 'Email domain(s)', 'First name attribute', 'Last name attribute', 'Email attribute', and 'External groups attribute'. Next is an enabled checkbox labeled 'Sign authentication requests'. Next is a disabled checkbox labeled 'Require signed assertions'.

    Note: You must manually disable a SAML identity provider created by PAS when you no longer require it.

  6. Set the Provider name. This is a unique name you create for the identity provider. This name can include only alphanumeric characters, +, _, and -. You should not change this name after deployment because all external users use it to link to the provider.

  7. Enter a Display name. Your provider display name appears as a link on your Pivotal login page, which you can access at https://login.YOUR-SYSTEM-DOMAIN. Login page

  8. Retrieve the metadata from your identity provider and copy it into either the Provider metadata or the Provider metadata URL fields, depending on whether your identity provider exposes a metadata URL or not. For more information, see Configure SAML as an Identity Provider for PAS. Pivotal recommends that you use the provider metadata URL rather than provider metadata because the metadata can change. You can do this in either of the following ways:

    • If your identity provider exposes a metadata URL, provide the metadata URL.
    • Download your identity provider metadata and paste this XML into the Provider metadata field.

      Note: You only need to select one of the above configurations. If you configure both, your identity provider defaults to the Provider metadata URL.

      Note: For information about onboarding SAML users and mapping them to PAS user roles, see Adding Existing SAML or LDAP Users to a Pivotal Platform Deployment.

  9. Select the Name ID format for your SAML identity provider. This translates to username in PAS. The default is Email Address.

  10. For Email domain(s), enter a comma-separated list of the email domains for external users who will receive invitations to Apps Manager.

  11. For First name attribute and Last name attribute, enter the attribute names in your SAML database that correspond to the first and last names in each user record. For example, first_name and last_name. This field is case-sensitive.

  12. For Email attribute, enter the attribute name in your SAML assertion that corresponds to the email address in each user record. For example, EmailID. This field is case-sensitive.

  13. For External groups attribute, enter the attribute name in your SAML database that defines the groups that a user belongs to. For example, group_memberships. To map the groups from the SAML assertion to admin roles in PAS, follow the procedure in the Grant Admin Permissions to an External Group (SAML or LDAP) section of the Creating and Managing Users with the UAA CLI (UAAC) topic. This field is case-sensitive.

  14. By default, all SAML authentication requests from PAS are signed. To change this, disable the Sign authentication requests checkbox and configure your identity provider to verify SAML authentication requests.

  15. To validate the signature for the incoming SAML assertions, enable the Required signed assertions checkbox and configure your identity provider to send signed SAML assertions.

  16. Click Save.

  17. Return to the Installation Dashboard by clicking the link.

  18. On the Installation Dashboard, click Review Pending Changes, then Apply Changes.

Configure SAML as an Identity Provider for PAS

To configure a SAML identity provider to designate PAS as a service provider:

  1. Download the service provider metadata from https://login.YOUR-SYSTEM-DOMAIN/saml/metadata. See the documentation from your identity provider for configuration instructions.

  2. See the table below for information about certain industry-standard identity providers and how to integrate them with PAS:

    Solution Name Integration Guide
    CA Single Sign-On aka CA SiteMinder Link
    Ping Federate Link
    Active Directory Federation Services Link

Note: Some identity providers allow uploads of service provider metadata. Other providers require you to manually enter the service provider metadata into a form. If your identity provider requires manual entry but is not listed above, see CA SiteMinder SSO Integration Guide.

Configure LDAP as an Identity Provider for PAS

To integrate the UAA with one or more LDAP servers:

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click the PAS tile.

  3. In the left navigation menu, select the Authentication and Enterprise SSO pane.

    There is a selected radio button labeled 'LDAP server'. Below this is a field labeled 'Server URL(s)', with a red asterisk to denote that it is a required field. It contains the ghost text 'ldaps://example.com'. Next is a set of two fields under the label 'LDAP credentials', with a red asterisk. The first contains the ghost text 'Username', and the second contains the ghost text 'Password'. Next is a field labeled 'User search base', with a red asterisk, containing the ghost text 'ou=Groups,dc=example,dc=com'. Next is a field labeled 'User search field', with a red asterisk, containing the text 'cn={0}'. Next is a field labeled 'Group search base', containing the ghost text 'ou=Groups,dc=example,dc=com'. Next is a field labeled 'Group search filter', with a red asterisk, containing the text 'member={0}'. Next is a field labeled 'Group maximum search depth ( min: 1, max: 10)', containing the text '1'. Next is a text area labeled 'Server SSL certificate'. Next are two fields labeled 'First name attribute' and 'Last name attribute'. Next is a field labeled 'Email attribute', with a red asterisk, containing the text 'mail'. Next is a field labeled 'Email domain(s)'. Next is a dropdown labeled 'LDAP referrals', with a red asterisk, with the option 'Automatically follow any referrals' selected.

  4. Under Configure your UAA user account store with either internal or external authentication mechanisms, select LDAP server.

  5. For Server URL(s), enter the URL that points your LDAP server. For multiple LDAP servers, enter a space-separated list. Each URL must include one of the following protocols:

    • ldap://: This specifies that the LDAP server uses an unencrypted connection.
    • ldaps://: This specifies that the LDAP server uses SSL for an encrypted connection and requires that the LDAP server holds a trusted certificate or that you import a trusted certificate to the JVM truststore.
  6. For LDAP credentials, enter the LDAP distinguished name (DN) and password for binding to the LDAP server. For example: cn=administrator,ou=Users,dc=example,dc=com

    Note: Pivotal recommends that you provide LDAP credentials that grant read-only permissions on the LDAP search base and the LDAP group search base. Additionally, if the bind user belongs to a different search base, you must use the full DN.

    Warning: Pivotal recommends against reusing LDAP service accounts across environments. LDAP service accounts should not be subject to manual lockouts, such as lockouts that result from users utilizing the same account. Also, LDAP service accounts should not be subject to automated deletions, since disruption to these service accounts could prevent user logins.

  7. For User search base, enter the location in the LDAP directory tree from which any LDAP user search begins. The typical LDAP search base matches your domain name.

    For example, a domain named “cloud.example.com” typically uses the following LDAP user search base: ou=Users,dc=example,dc=com

  8. For User search filter, enter a string that defines LDAP user search criteria. These search criteria allow LDAP to perform more effective and efficient searches. For example, the standard LDAP search filter cn=Smith returns all objects with a common name equal to Smith.

    In the LDAP search filter string that you use to configure PAS, use {0} instead of the username. For example, use cn={0} to return all LDAP objects with the same common name as the username.

    In addition to cn, other attributes commonly searched for and returned are mail, uid and, in the case of Active Directory, sAMAccountName.

    Note: For instructions for testing and troubleshooting your LDAP search filters, see Configuring LDAP Integration with Pivotal Cloud Foundry in the Pivotal Knowledge Base.

  9. For Group search base, enter the location in the LDAP directory tree from which the LDAP group search begins.

    For example, a domain named “cloud.example.com” typically uses the following LDAP group search base: ou=Groups,dc=example,dc=com

    This is required if you are mapping LDAP groups to an admin role. To map the groups under this search base to admin roles in PAS, see the Grant Admin Permissions to an External Group (SAML or LDAP) section of the Creating and Managing Users with the UAA CLI (UAAC) topic.

    Note: To onboard individual LDAP users and map them to PAS roles, see Adding Existing SAML or LDAP Users to a Pivotal Platform Deployment.

  10. For Group search filter, enter a string that defines LDAP group search criteria. The standard value is member={0}. This is required if you are mapping LDAP groups to an admin role.

  11. For Maximum group search depth, enter a value between 1 and 10 that sets the maximum LDAP group search depth. The default value, 1, turns off nested group search.

  12. For Server SSL certificate, paste in the root certificate from your CA certificate or your self-signed certificate. This is required only for ldaps:// URLs.

  13. For First name attribute and Last name attribute, enter the attribute names in your LDAP directory that correspond to the first and last names in each user record. For example, cn and sn.

  14. For Email attribute, enter the attribute name in your LDAP directory that corresponds to the email address in each user record. For example, mail.

  15. For Email domain(s), enter a comma-separated list of the email domains for external users who will receive invitations to Apps Manager.

  16. For LDAP referrals, select how the UAA handles LDAP server referrals out to other external user stores. The UAA can:

    • Automatically follow any referrals.
    • Ignore referrals and return partial result.
    • Throw exception for each referral and abort.
  17. Click Save.

  18. Return to the Installation Dashboard.

  19. On the Installation Dashboard, click Review Pending Changes, then Apply Changes.