This is a recipe for
Platform Operators
andSpace 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.
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.
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.
https://login.system.pcf.local
.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.
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.
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-internal
.)cf marketplace
in a
terminal window.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.
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.
Service instances are created based on the service plan and are visible within the confines of a space.
To create a new service instance:
https://console.system.pcf.local
as a Space Developer.Pivotal Single Sign-On
.Instance Name
.development
.[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.
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.
Target the system domain.
$ uaac target https://login.system.pcf.local --skip-ssl-validation
Fetch your admin client token.
$ uaac token client get admin
Client secret:
When prompted with Client secret
, enter your Admin Client
Credentials located in teh Credentials tab of your Pivotal
Elastic Runtime tile.
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"
Target your system domain.
$ uaac target https://login.system.pcf.local
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
When prompted with Client ID
, type identity
and press enter.
For Client secret
, enter your Identity Client Credentials,
located in the Credentials tab of your Pivotal Elastic Runtime tile.
For User name
, enter admin
.
Enter your Password
, which is located in the Admin
Credentials under the Credentials tab of your Pivotal Elastic
Runtime tile.
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.
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
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
Fetch the token for your Service Plan admin client.
$ uaac token client get service_plan_admin_client
Client secret:
When prompted with Client secret
, enter the secret
from the
uaac curl
command above.
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
(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
Secure your applications in one of the following ways:
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:
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.
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.