Managing Service Plans

This topic describes how Pivotal Cloud Foundry (PCF) Administrators manage Single Sign-On service plans.

Single Sign-On (SSO) is a multi-tenant service, which enables a deployment to host multiple tenants as service plans. Each service plan can have its own administrators, applications and users. This lets enterprises segregate access by using separate plans. For example, the following tenants might require separate plans:

  • Business units and geographical locations

  • Employees, consumers, and partners

  • Development, staging, and production instances

You may also want to configure an SSO Service Plan as an OpenID Connect (OIDC) identity provider. For more information, see Plan-to-Plan OIDC Integration Guide.

Create or Edit Service Plans

PCF administrators can create new SSO service plans at any time from the SSO Operator Dashboard. You can use the SSO Operator Dashboard to create and configure service plans at any time.

Note: You must create at least one plan for any service before your applications can use it.

  1. Log into the SSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your User Account and Authentication (UAA) administrator credentials. You can find these credentials in the Pivotal Application Service (PAS) tile in Ops Manager in the Credentials tab.

  2. Click New Plan on the SSO Operator Dashboard to create a new SSO service plan.

    Managing create plan

  3. Enter a Plan Name.

  4. Enter a Description to appear as a plan feature in the Services Marketplace.

  5. Enter an Auth Domain to be the URL where users authenticate to access applications covered by the service plan.

  6. Enter an Instance Name to appear on the login page and in other user-facing content, such as email communications.

  7. Add Plan Administrators. These users can view the plan and manage identity providers.

    Note: You cannot add system operators to this list. System operators do not appear in this list because they already have Plan Administrator privileges.

  8. Under Organizations, select specific organizations in your PCF deployment that can access your Single Sign-On service plan, or select Enable for all Orgs.

    • If you select Enable for all Orgs the plan is available for use and displayed in the Services Marketplace for all developers in any organization. This is only recommended for test plans to allow developers to experiment with the SSO service.

    • If you do not select any organizations, the plan is not available for use and it is not displayed in the Services Marketplace.
  9. Click Create Plan. Your new plan appears in the Services Marketplace in the organizations you selected. Users in those organizations view the plan either in Apps Manager or through the CF CLI by entering cf marketplace in a terminal window.

Delete Service Plans

Note: This action cannot be undone. Deleting a Single Sign-On service plan removes from the SSO database all of the configurations, identity providers, users, application configurations and resources associated with the plan. It also deletes the associated service instances and service bindings. You must rebind any applications bound to the deleted service instances to new service instances.

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

  2. Select the name of the plan you want to delete, and click Edit Plan in the drop-down menu.

  3. Select Delete at the bottom of the page.

  4. In the popup that appears, click Delete Plan to confirm that you want to delete the plan.

Automate Service Plan Creation Using SSO API

PCF administrators can create new SSO service plans using the SSO API. This allows them to automate creating and deleting SSO plans. Pivotal recommends creating a dedicated client for SSO plan automation.

To automate service plan creation, do the following:

  1. To install the UAA CLI, run the following command:

    gem install cf-uaac
    
  2. To target your PCF UAA server, run the following command:

    $ uaac target uaa.YOUR-SYSTEM-DOMAIN
    

    Where YOUR-SYSTEM-DOMAIN is your PCF system domain URL.

  3. To record your admin credentials, do one of the following:

    • Obtain Admin Client Credentials from Ops Manager.
    • Obtain uaa:admin:client_secret from your deployment manifest.
  4. To authenticate and obtain an access token for the admin client from the UAA server, run the following command:

    uaac token client get admin -s ADMIN-CLIENT-SECRET
    

    Where ADMIN-CLIENT-SECRET is the admin credentials you recorded in step 3.

    UAAC stores the token in ~/.uaac.yml.

  5. To create an automation client with UAAC, run the following command:

    uaac client add AUTO-CLIENT-ID --secret AUTO-CLIENT-SECRET \
    --authorized_grant_type client_credentials \
    --authorities "cloud_controller.admin,zones.write,scim.write,scim.read"
    

    Where:

    • AUTO-CLIENT-ID is the name of the automation client you want to use.
    • AUTO-CLIENT-SECRET is the secret for the automation client you want to use.
  6. To obtain an access token for your automation client, run the following command:

    uaac token client get AUTO-CLIENT-ID -s AUTO-CLIENT-SECRET
    

    Where:

    • AUTO-CLIENT-ID is the name you provided in step 5.
    • AUTO-CLIENT-SECRET is the secret you provided in step 5.
  7. To obtain your automation access token, run the following command:

    uaac context
    

    For example:

    $ uaac context
    
    [1]*[my-auto-client]
    client\_id: my-client-id
        access\_token: aBcdEfg0hIJKlm123.e
        token\_type: bearer
        expires\_in: 43200
        scope: cloud\_controller.admin zones.write scim.write scim.read
        jti: 91b3-abcd1233
    
  8. Record the access_token value from the output of the previous step.

  9. To create a new SSO plan and record the plan ID, run the following command:

    curl -X POST "https://sso-api.YOUR-SYSTEM-DOMAIN/v1/plans" \
      -H "Authorization: Bearer YOUR-TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "YOUR-PLAN-NAME",
        "description": "YOUR-DESCRIPTION",
        "auth_domain": "YOUR-AUTH-DOMAIN",
        "instance_name": "YOUR-INSTANCE-NAME"
      }'
    

    Where:

    • YOUR-SYSTEM-DOMAIN is your PCF system domain URL.
    • YOUR-TOKEN is the access token you recorded from the previous step.
    • YOUR-PLAN-NAME is the name of your plan.
    • YOUR-DESCRIPTION is the text you want to appear as a plan feature in the Services Marketplace.
    • YOUR-AUTH-DOMAIN is the subdomain of the login.YOUR-SYSTEM-DOMAIN URL where users authenticate to access applications covered by the service plan.
    • YOUR-INSTANCE-NAME is the name of your instance. This text appears in user-facing content, such as email communications.

    The above command returns output similar to the following:

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
      "id": "1",
      "name": "some-plan-name",
      "description": "some-description",
      "auth\_domain": "some-auth-domain",
      "instance\_name": "some-instance-name"
    }
    
  10. Record the id value from the output of the previous step.

    Alternatively, you can save the plan ID, by parsing the output from the previous step. For example, you can run the following command:

    $PLAN-ID=$(curl -X POST "https://sso-api.YOUR-SYSTEM-DOMAIN/v1/plans"  \
      -H "Authorization: Bearer YOUR-TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "YOUR-PLAN-NAME",
        "description": "YOUR-DESCRIPTION",
        "auth_domain": "YOUR-AUTH-DOMAIN",
        "instance_name": "YOUR-INSTANCE-NAME"
      }' | jq -r '.id')
    

    Where YOUR-SYSTEM-DOMAIN is your PCF system domain URL.

    Note: Using curl instead of uaac curl in the example to facilitates parsing the response for ID below.

  11. To add plan administrators, who can view the plan and manage identity providers, run the following command for each plan administrator:

    uaac member add zones.PLAN-ID.admin USER-NAME
    

    Where:

    • PLAN-ID is the id recorded in the previous step.
    • USER-NAME is the username of the plan administrator you are adding.
  12. To authenticate as your automation client, run the following commands:

    cf api api.YOUR-SYSTEM-DOMAIN
    cf auth AUTO-CLIENT-ID AUTO-CLIENT-SECRET --client-credentials
    

    Where:

    • YOUR-SYSTEM-DOMAIN is your PCF system domain URL.
    • AUTO-CLIENT-ID is the name you provided in step 5.
    • AUTO-CLIENT-SECRET is the secret you provided in step 5.
  13. To give orgs access to your SSO plan, do one of the following:

    • To give specific orgs access to your SSO plan, run the following command for each org:

      cf enable-service-access p-identity -p YOUR-AUTH-DOMAIN -o ORG-NAME
      

      Where:

      • YOUR-AUTH-DOMAIN is the subdomain you provided in step 9.
      • ORG-NAME is the name of the org you want to have access to your SSO plan.
    • To give all orgs access to your SSO plan, run the following command:

      cf enable-service-access p-identity -p PLAN_AUTH_DOMAIN
      

      Where YOUR-AUTH-DOMAIN is the subdomain you provided in step 9.

      Pivotal recommends only giving all orgs acess to your SSO plans for test plans to allow developers to experiment with the SSO service.

For more information on how you can manage SSO plans using the SSO API, see the SSO API documentation.

Create a New PCF Administrator for SSO

PCF administrators can grant users additional permissions to allow them to manage SSO plans. These permissions let users act as PCF administrators.

WARNING: If you use external group mappings, create group mappings for these scopes instead. If you follow the below procedure, permissions are directly assigned to your users. For more information, see Grant Admin Permissions to an External Group (SAML or LDAP).

To create a new PCF administrator, do the following:

  1. To install the UAA CLI, run the following command:

    gem install cf-uaac
    
  2. To target your PCF UAA server, run the following command:

    $ uaac target uaa.YOUR-SYSTEM-DOMAIN
    

    Where YOUR-SYSTEM-DOMAIN is your PCF system domain URL.

  3. To record your admin credentials, do one of the following:

    • Obtain Admin Client Credentials from OpsManager.
    • Obtain uaa:admin:client_secret from your deployment manifest. UAAC stores the token in ~/.uaac.yml.
  4. To authenticate and obtain an access token for the admin client from the UAA server, run the following command:

    uaac token client get admin -s ADMIN-CLIENT-SECRET
    

    Where ADMIN-CLIENT-SECRET is the admin credentials you recorded in step 3.

  5. To allow users to manage SSO plans, run the following commands:

    uaac member add cloud_controller.admin ADMIN-USERNAME
    uaac member add scim.read ADMIN-USERNAME
    uaac member add zones.read ADMIN-USERNAME
    uaac member add zones.write ADMIN-USERNAME
    

    Where ADMIN-USERNAME is the username of the user you want to make an administrator.