Browse Recipes

Pivotal SSO Configuration

sso uaa security

This is a recipe for Platform Operators and Space Developers. In order to install and configure the Pivotal Single Sign-On tile, you must have rights to Ops Manager. In order to configure a SSO service instance and bind applications to it, you must be a space developer on a space within an org to which the SSO tile was provisioned.

This recipe describes the steps necessary to install and configure the Pivotal Platform Single Sign-On tile backed by an internal user store. These steps are more or less taken directly from the references listed at the bottom of this document, with additional context provided, as well as corrections to the documentation. Over time, it might be prudent to prefer the original sources as they are curated, while this recipe is not.

Platform Operator Tasks

Before the Pivotal Platform SSO tile can be consumed by developers and bound to their applications, it is necessary for a platform administrator (Pivotal refers to them as Operators) to install, configure, and provision the tile to a given space.

Step 1: Install the Service Tile in Ops Manager

  1. Download the Pivotal Platform Single Sign-On product tile from Pivotal Network.
  2. Upload the product tile to your Ops Manager installation. See Adding and Deleting Products.
  3. Click Add next to the uploaded product description in the Available Products view to add this product to your staging area.
  4. Click Apply Changes to deploy the service.

Tip Steps 1,2 & 4 will require the Operator to Apply Changes. Currently, applying changes will attempt to redeploy everything. While BOSH is smart enough to skip several steps, there are typically several errands associated with each tile that will run. Depending on the maturity of your Cloud Foundry configuration, you may be able to avoid unnecessarily long deploy cycles by temporarily disabling some errands.

Step 2: Configure Elastic Runtime

  1. From the Installation Dashboard, click the Elastic Runtime tile.
  2. Select SSO Config on the Settings tab.
  3. Under Provider Name, enter https://login.system.pcf.local.
  4. Under Provider Metadata URL, enter https://login.system.pcf.local/saml/metadata. Or download your metadata from https://login.system.pcf.local/saml/metadata and enter it under Provider Metadata area.
  5. Click Save.
  6. Return to the Installation Dashboard and, once again, click Apply Changes.

Note These steps reference *.system.pcf.local URLs. This represents the System Domain. In new deployments of Pivotal Platform, you will need to replace this with your actual system domain.

Step 3: Configure SSO via the Dashboard

After Ops Manager has finished applying your changes, login to the SSO dashboard at https://p-identity.system.pcf.local using your UAA administrator credentials. You can find those credentials in the Pivotal Elastic Runtime tile under the Credentials tab.

From the SSO dashboard, create a new Single Sign-On Service Plan by clicking New Plan.

SSO Plan Details

  1. Choose a Plan Name, and enter a Description.
  2. Enter an Auth Domain, which is the URL your users will enter to access their Single Sign-On Service Plan. (For our install we named our auth domain sso-internal.)
  3. Choose an Instance Name. The instance name appears on the login page and in other user-facing content, such as email communications.
  4. Under Org Visibility, select which organizations should have access to your Single Sign-On Service Plan. If you do not select any orgs, that plan will be completely hidden in the Services Marketplace.
  5. Click Save Plan. Your new plan will appear in the Apps Manager Marketplace to users in the organizations you have selected. You can also access the Solutions Hub by entering cf marketplace in a terminal window.

Step 4: Update SSL Certificates

As described in the above section, every service plan corresponds to a tenant. Each service plan is accessible at a tenant-specific URL in the format https://sso-internal.login.system.pcf.local.

You must update the SSL Certificate for the domains listed below. In addition, depending on your infrastructure and type of load balancer, update your load balancer configuration for the following domains:

   *.system.pcf.local
   *.apps.pcf.local
   *.login.system.pcf.local
   *.uaa.system.pcf.local

Note Certificates are updated via the Elastic Runtime Tile in Ops Manager on the Security Config panel.

After updating your SSL Certificate as described above, it will be necessary to Save and Apply Changes one last time.

This concludes the Platform Operator portion of this recipe. Assuming you have Space Developer credentials on a space in an org to which the SSO tile was provisioned (in our case dap), proceed to the next section to create and configure a service instance to be used by your applications.

Space Developer Tasks

After you have made the plans visible in the relevant Pivotal Platform organizations, create a service instance to use the service plan within a space.

While service instances are accessible only within a space, service plans are visible across spaces and orgs. Every plan needs a service instance in every space containing applications it will access.

If you have a plan that allows Single Sign-On to applications in multiple spaces, you must create a service instance for the plan in each of the spaces.

Step 1: Create a Service Instance

Service instances are created based on the service plan and are visible within the confines of a space.

To create a new service instance:

  1. Log in to your Apps Manager instance at https://console.system.pcf.local as a Space Developer.
  2. Navigate to the Marketplace and select Pivotal Single Sign-On.
  3. Select your service plan.
  4. Enter an Instance Name.
  5. Choose a space for the instance from the Add to Space dropdown menu. The default is development.
  6. Choose an application to bind the service instance to from the Bind to App dropdown menu. This option defaults to [do not bind].

Note Unless you already have an OAuth-aware application deployed in the selected space, leave the Bind to App value as [do not bind]. We will configure and bind an app to this service instance later on.

Configure SSO Instance

Step 2: Configure the Identity Provider

Note The Pivotal SSO Tile documentation instructs us to configure an external identity provider at this point. However, this recipe leverages UAA as the internal user store.

In order to add users to the Internal User Store for a given Service Plan, you must use the UAA Command Line Interface (UAAC). If you do not already have the UAAC installed, run gem install cf-uaac in a terminal window.

The following steps describe how to use UAAC to add users to your Service Plans.

Step 2a: Client Registration

  1. Target the system domain. $ uaac target https://login.system.pcf.local --skip-ssl-validation

  2. Fetch your admin client token. $ uaac token client get admin Client secret:

  3. When prompted with Client secret, enter your Admin Client Credentials located in teh Credentials tab of your Pivotal Elastic Runtime tile.

  4. Update client registrations for identity and add password as a supported authorization grant type. $ uaac client update identity --authorized_grant_types "refresh_token, password, client_credentials, authorization_code"

Step 2b: Client Creation

  1. Target your system domain. $ uaac target https://login.system.pcf.local

  2. Use the identity client and the administrator user credentials to retrieve a token which allows client creation in a given identity zone. $ uaac token owner get

  3. When prompted with Client ID, type identity and press enter.

  4. For Client secret, enter your Identity Client Credentials, located in the Credentials tab of your Pivotal Elastic Runtime tile.

  5. For User name, enter admin.

  6. Enter your Password, which is located in the Admin Credentials under the Credentials tab of your Pivotal Elastic Runtime tile.

  7. Find the Identity Zone ID of your Service Plan by logging into the SSO dashboard, selecting Edit Plan, and copying the Identity Zone ID from the URL.
    SSO URL

The highlighted text in the example URL above is the Identity Zone ID of the Service Plan.

Finally, execute the following command, replacing YOUR-IDENTITY-ZONE-ID with the Identity Zone ID of your Service Plan. You can also replace service_plan_admin_client with a different name for your client, and secret with a different client secret. $ uaac curl -k -H"Accept:application/json" -H"Content-Type:application/json" -H"X-Identity-Zone-Id:YOUR-IDENTITY-ZONE-ID" -XPOST --data '{"client_id":"service_plan_admin_client", "client_secret":"secret", "authorized_grant_types":["client_credentials"], "authorities":["scim.write", "clients.admin","scim.read"]}' /oauth/clients

Step 2c: User Creation

  1. Target the auth domain of your Single Sign-On Service Plan. This is the URL you provided when creating a Service Plan in the SSO dashboard. (In our case, the auth domain that was set up ealier in this recipe is sso-internal.) $ uaac target https://sso-internal.login.system.pcf.local

  2. Fetch the token for your Service Plan admin client. $ uaac token client get service_plan_admin_client Client secret:

  3. When prompted with Client secret, enter the secret from the uaac curl command above.

  4. Add new users by provided the user's email address, username, and password. $ uaac user add --emails USER@EMAIL.COM User name: USER Password: ******** Verify password: ******** user account successfully added

  5. (Optional) You can also create group and add users to them. $ uaac group add Group name: 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: GROUP

To add a member to your new group, use the following command. $ uaac member add GROUP USER

Step 3: Register an Application

Secure your applications in one of the following ways:

  • Bind your application to a service instance from the Apps Manager Console.
  • Register your application from the Pivotal Single Sign-On service dashboard.

When you bind an application with the Pivotal Single Sign-On service, an OAuth Client is registered with the Single Sign-On server. This OAuth Client acts as an OAuth 2.0 Authorization Server and issues tokens.

If you bind your application from the Apps Manager Console, then you are choosing the following defaults:

  • The application type is Web App.
  • The User Store Connection is an Internal User Store. This means that users are stored in the user store provided by Pivotal Single Sign-On.

If you register your application with the Pivotal Single Sign-On service dashboard, you gain access to a larger selection of application types. You can also configure the User Store Connection to an external identity provider with SAML.

Step 4: Enable OAuth2 for Applications

Your application must be able to request and validate an OAuth or OpenID Connect token. Refer to the Application Integration section for general information regarding how to integrate with the Pivotal SSO tile.

References

  1. Getting Started with Pivotal Single Sign-On
  2. Administering Pivotal Single Sign-On
  3. Adding Users to a Single Sign-On Service Plan
  4. Choosing an Application Type