Managing Service Plans

This topic describes how Pivotal Platform Administrators manage Single Sign-On service plans.

Pivotal Single Sign‑On 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 Pivotal Single Sign‑On as an OpenID Connect (OIDC) identity provider. For more information, see Plan-to-Plan OIDC Integration Guide.

Create or Edit Service Plans

Pivotal Platform administrators can create new Pivotal Single Sign‑On 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 apps 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 tile in Ops Manager in the Credentials tab.

  2. Click New Plan on the SSO Operator Dashboard to create a new Pivotal Single Sign‑On 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 Pivotal Platform deployment that can access your Pivotal 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 Pivotal Single Sign‑On.

    • 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 Pivotal Single Sign‑On service plan removes from the Pivotal Single Sign‑On 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 SSSO Operator Dashboard at https://p-identity.YOUR-SYSTEM-DOMAIN using your UAA administrator credentials. You can find these credentials in your 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 Pivotal Single Sign‑On API

Pivotal Platform administrators can create new Pivotal Single Sign‑On service plans using the Pivotal Single Sign‑On API. This allows them to automate creating and deleting Pivotal Single Sign‑On plans. Pivotal recommends creating a dedicated client for Pivotal Single Sign‑On 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 Pivotal Platform UAA server, run the following command:

    $ uaac target uaa.YOUR-SYSTEM-DOMAIN
    

    Where YOUR-SYSTEM-DOMAIN is your Pivotal Platform 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 Pivotal Single Sign‑On 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 Pivotal Platform 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 Pivotal Platform 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 Pivotal Platform 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 Pivotal Single Sign‑On plan, do one of the following:

    • To give specific orgs access to your Pivotal Single Sign‑On 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 Pivotal Single Sign‑On plan.
    • To give all orgs access to your Pivotal Single Sign‑On 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 access to your Pivotal Single Sign‑On plans for test plans to enable developers to experiment with Pivotal Single Sign‑On.

For more information on how you can manage Pivotal Single Sign‑On plans using the Pivotal Single Sign‑On API, see the Pivotal Single Sign‑On API documentation.

Create a New Pivotal Platform Administrator for Pivotal Single Sign‑On

Pivotal Platform administrators can grant users additional permissions to allow them to manage Pivotal Single Sign‑On plans. These permissions let users act as Pivotal Platform 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 Pivotal Platform administrator, do the following:

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

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

    $ uaac target uaa.YOUR-SYSTEM-DOMAIN
    

    Where YOUR-SYSTEM-DOMAIN is your Pivotal Platform 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 Pivotal Single Sign‑On 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.