Configuring Apps

This topic explains how Pivotal Platform developers configure their apps to use Pivotal Single Sign‑On and use the SSO Admin Client to manage connections between SSO identity providers, apps, users, and other resources.

Overview

Pivotal Single Sign‑On enables users to log in through a single sign-on service and access other apps that are hosted or protected by the service. Eliminating the need for users to log in to individual apps improves security and productivity.

Register an App

Follow the instructions below to register an app for Pivotal Single Sign‑On.

Prerequisites for Registering Apps

Before you can register your app for Pivotal Single Sign‑On, you must create a service instance and choose your Pivotal Single Sign‑On app type as follows:

  1. Create a service instance by doing the procedure in Create Service Instances.

  2. Determine your app’s Pivotal Single Sign‑On app type. This informs which OAuth Grant Type you should use for your app. For more information, see Determining Pivotal Single Sign‑On Application Type.

    Note: If your app is a resource server, you do not need to register the app because it only consumes tokens and does not handle any token acquisition flow itself. A resource server hosts protected resources and accepts and responds to protected resource requests using access tokens, such as an API.

  3. Choose a method to register your app with the Pivotal Single Sign‑On service:

Register a Pivotal Platform App

To configure Pivotal Single Sign‑On for a Pivotal Platform app, use one of the following methods:

Note: Apps that have environment variables set using the app manifest do not work with cf bind-service. If you have leftover environment variables previously set using the app manifest, you need to remove them with cf unset-env APP-NAME PROPERTY-NAME before you perform a service bind.

Configure Pivotal Single Sign‑On Properties with JSON Bind Parameters

In Pivotal Single Sign‑On v1.7.0 and later, you can use a JSON file or string containing bind parameters to configure Pivotal Single Sign‑On properties. For more information about bind parameters, see Bind Parameters below.

To configure Pivotal Single Sign‑On properties with JSON bind parameters, run the following command:

cf bind-service APP-NAME INSTANCE-NAME -c JSON

Where:

  • APP-NAME is the name of your app.
  • INSTANCE-NAME is the name of the service instance you are binding.
  • JSON is the path to the JSON file or the full JSON string containing bind parameters.

For example:

$ cf bind-service my-app my-instance -c example.json
Binding service my-instance to my-app in org my-org / space test as user@example.com...
OK

$ cat example.json
{
    "grant_types": ["authorization_code"],
    "scopes": ["openid", "todo.read", "todo.write"],
    "authorities": ["openid", "uaa.resource", "todo.read", "todo.write"],
    "redirect_uris": ["https://my-app.example.com/**","http://my-app.example.com/path/to/app"],
    "auto_approved_scopes": ["openid", "todo.read"],
    "identity_providers": ["uaa","ldap","my-saml-provider"],
    "required_user_groups": ["openid","todo.read"],
    "resources": {"todo.read" : "Read to list", "todo.write": "Write to list"},
    "access_token_lifetime": 300,
    "refresh_token_lifetime": 86400,
    "icon": "R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==",
    "launch_url": "http://my-app.example.com",
    "show_on_home_page": true
}

For more information about the cf bind-service command, see bind-service in the Cloud Foundry CLI Reference Guide.

You can also bind service instances with Apps Manager. For more information, see Bind a Service Instance to an Application.

Bind Parameters

The table below provides descriptions and default values for bind parameters:

Property Name Description Default
grant_types The following grant types are supported by Pivotal Single Sign‑On:
  • authorization_code
  • password
  • client_credentials
  • implicit
If you want to use more than one grant type, you can only use the authorization_code and client_credentials grant types at the same time. Otherwise, you can only use one grant type per app.
identity_providers Allowed identity providers for the app through the Pivotal Single Sign‑On service plan. This is a comma-separated list of identity provider origin keys.

The origin keys are derived from the identity provider name using the following rules:
  • Uppercase letters are converted to lowercase letters.
  • Spaces, periods, and underscores are converted to hyphens.
  • Multiple hyphens are combined into a single hyphen.
For example, if your identity provider name is example.com Provider, the corresponding origin key is example-com-provider.
uaa
redirect_uris Comma-separated allow list of redirection URIs allowed for the app. Each value must be a valid URI. Custom URIs are supported for mobile apps. Always includes the app route
scopes Comma-separated list of scopes that belong to the app and are registered as client scopes with Pivotal Single Sign‑On. This value is ignored for client credential grant type apps. openid
auto_approved_scopes Comma-separated list of scopes that the app is automatically authorized when acting on behalf of users through Pivotal Single Sign‑On. Defaults to existing scopes/authorities
authorities Comma-separated list of authorities that belong to the app and are registered as client authorities with Pivotal Single Sign‑On. Privileged identity zone/plan admin scopes, such as scim.read, idps.write cannot be bootstrapped and must be assigned by zone/plan admins. This value is ignored for any grant type other than client credentials. uaa.resource
required_user_groups Comma-separated list of groups a user must have to log in to the app. No value
access_token_lifetime Lifetime in seconds for the access token issued to the app by Pivotal Single Sign‑On. 43200
refresh_token_lifetime Lifetime in seconds for the refresh token issued to the app by Pivotal Single Sign‑On. 2592000 (not used for client credentials)
resources Resources for the app to use as scopes and authorities for Pivotal Single Sign‑On created during bind, if they do not already exist. All permissions within the same top level permission, such as todo.read and todo.write, must be specified in the same bind command. You cannot specify additional permissions in the same top level permission, such as todo.admin, in additional binds. No value
icon App icon displayed next to the app name on the Pivotal Account dashboard. It is displayed if show_on_home_page is set to true. Do not exceed 64kb. No value
launch_url App launch URL used for the app on the Pivotal Account dashboard if show_on_home_page is set to true. The application route
show_on_home_page If set to true, the app appears on the Pivotal Account dashboard with the corresponding icon and launch URL. true

Configure Pivotal Single Sign‑On Properties with the App Manifest

If you configure Pivotal Single Sign‑On properties with the app manifest, you do not need to manually bind your app to the service instance after you deploy your app. Pivotal Single Sign‑On reads its configuration properties from environment variables that are set in the apps that use it.

Note: These configurations are only applied at the time of the initial service bind. If you run cf push again, the app does not update the configurations. You can update the configurations through the SSO Developer Dashboard.

To register your app with the app manifest, do the following in your app manifest:

  1. Specify the Pivotal Single Sign‑On service instance you want to bind your app. For an example, see the services section in the YAML sample below.
  2. Configure the Pivotal Single Sign‑On configuration properties in your app manifest. For an example, see the properties in the env section in the YAML sample below.

The snippet below shows how to register your app with a Pivotal Single Sign‑On service instance and how to configure the GRANT_TYPE and SSO_IDENTITY_PROVIDERS Pivotal Single Sign‑On properties in your manifest.

---
applications:
  - name: my-example-app
    services:
    - my-sso-sample-instance
    env:
      GRANT_TYPE: implicit
      SSO_IDENTITY_PROVIDERS: uaa, sample-identity-provider

For examples of configuring Pivotal Single Sign‑On properties in an app manifest, see the manifest.yml files in the identity-sample-apps GitHub repository.

The table below provides descriptions and default values for Pivotal Single Sign‑On properties to include in the app manifest:

Property Name Description Default
name Name of the app n/a. This value is required.
GRANT_TYPE The following grant types are supported by Pivotal Single Sign‑On:
  • authorization_code
  • password
  • client_credentials
  • implicit
If you want to use more than one grant type, you can only use the authorization_code and client_credentials grant types at the same time. Otherwise, you can only use one grant type per app.
authorization_code(Web application type)
SSO_IDENTITY_PROVIDERS Allowed identity providers for the app through the Pivotal Single Sign‑On service plan. This is a comma-separated list of identity provider origin keys. The origin keys are derived from the identity provider name using the following rules:
  • Uppercase letters are converted to lowercase letters.
  • Spaces, periods, and underscores are converted to hyphens.
  • Multiple hyphens are combined into a single hyphen.
For example, if your identity provider name is example.com Provider, the corresponding origin key is example-com-provider.
uaa(Pivotal Platform internal user store)
SSO_REDIRECT_URIS Comma-separated allow list of redirection URIs for the app. Each value must be a valid URI. Custom URIs are supported for mobile apps. (Always includes the app route)
SSO_SCOPES Comma-separated list of scopes that belong to the app and are registered as client scopes with Pivotal Single Sign‑On. This value is ignored for client credential grant type apps.

Pivotal recommends including openid, which is not added to your user-provided list by default.
openid
SSO_AUTO_APPROVED_SCOPES Comma-separated list of scopes that the app is automatically authorized when acting on behalf of users through Pivotal Single Sign‑On. (Defaults to existing scopes and authorities)
SSO_AUTHORITIES Comma-separated list of authorities that belong to the app and are registered as client authorities with Pivotal Single Sign‑On. Privileged identity zone and plan admin scopes, such as scim.read, idps.write cannot be bootstrapped and must be assigned by zone and plan admins. This value is ignored for any grant type other than client credentials.

Pivotal recommends including uaa.resource, which is not added your user-provided list by default.
uaa.resource
SSO_REQUIRED_USER_GROUPS Comma-separated list of groups a user must have to authenticate successfully for the app. (No value)
SSO_ACCESS_TOKEN_LIFETIME Lifetime in seconds for the access token issued to the app by Pivotal Single Sign‑On. 43200
SSO_REFRESH_TOKEN_LIFETIME Lifetime in seconds for the refresh token issued to the app by Pivotal Single Sign‑On. 2592000 (not used for client credentials)
SSO_RESOURCES Resources that the app uses as scopes and authorities for Pivotal Single Sign‑On to be created during bootstrapping if they do not already exist. The input format can be referenced in the provided sample manifest. Currently, all permissions within the same top-level permission, such as todo.read and todo.write, must be specified in the same app manifest. Currently you cannot specify additional permissions in the same top level permission, such as todo.admin, in additional app manifests. (No value)
SSO_ICON App icon that is displayed next to the app name on the Pivotal Account dashboard if Show on Homepage is enabled. Do not exceed 64kb. (No value)
SSO_LAUNCH_URL App launch URL that is used for the app on the Pivotal Account dashboard if Show on Homepage is enabled. (App route)
SSO_SHOW_ON_HOME_PAGE If set to true, the app appears on the Pivotal Account dashboard with the corresponding icon and launch URL. true

For more information and app manifest examples, see the identity-sample-apps GitHub repository.

Register an Externally Hosted App

To configure Pivotal Single Sign‑On for an app not hosted by Pivotal Platform, use one of the following methods:

Register an Externally Hosted App Using Service Keys

You can use a JSON file or string containing bind parameters to register an externally hosted app using service keys. For more information about bind parameters, see Bind Parameters above.

Service keys enable you to register apps for automation, such as scripts or pipelines.

To register an externally hosted app using service keys:

  1. To create a service key, run the following command:

    cf create-service-key INSTANCE-NAME SERVICE-KEY -c JSON
    

    Where:

    • INSTANCE-NAME is the name of your service instance.
    • SERVICE-KEY is the name you want for your service key.
    • JSON is the path to the JSON file or the full JSON string containing bind parameters.

    You must include the name parameter in your JSON file or string. The value of name is the user-defined name of your externally hosted app.

    For example:

    $ cf create-service-key my-instance my-service-key -c example.json
    Creating service key my-service-key for service instance my-instance as user@example.com...
    OK
    
    $ cat example.json
    {
        "name": "my-app",
        "grant_types": ["authorization_code"],
        "scopes": ["openid", "todo.read", "todo.write"],
        "authorities": ["openid", "uaa.resource", "todo.read", "todo.write"],
        "redirect_uris": ["https://my-app.example.com/**","http://my-app.example.com/path/to/app"],
        "auto_approved_scopes": ["openid", "todo.read"],
        "identity_providers": ["uaa","ldap","saml"],
        "required_user_groups": ["openid","todo.read"],
        "resources": {"todo.read" : "Read to list", "todo.write": "Write to list"},
        "access_token_lifetime": 300,
        "refresh_token_lifetime": 86400,
        "icon": "R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==",
        "launch_url": "http://google.com",
        "show_on_home_page": false
    }
    

    For more information about the cf create-service-key command, see create-service-key in the Cloud Foundry CLI Reference Guide.

  2. To obtain the service key credentials, run the following command:

    cf service-key INSTANCE-NAME SERVICE-KEY
    

    Where:

    • INSTANCE-NAME is the name of your service instance.
    • SERVICE-KEY is the name of the service key you created in step 1.

    For more information about how to use these values, see Integrate Pivotal Single Sign‑On with Your App.

    Note: client_credentials grant types, administrative scopes, and scopes in other spaces are not available. These must be manually added by a plan admin or system operator through the SSO Operator Dashboard or UAA CLI.

Register an Externally Hosted App Using the SSO Developer Dashboard

To register an externally hosted app using the SSO Developer Dashboard:

  1. Determine the Pivotal Single Sign‑On app type for your app. For more information, see Determining Pivotal Single Sign‑On Application Type.
  2. Log in to Apps Manager as a Space Developer.
  3. Select the space where your service instance is located.
  4. Under Services, click Manage next to the Pivotal Single Sign‑Onservice instance. This launches the SSO Developer Dashboard.

    SSO Developer Dashboard View a larger version of this image.

  5. Click Register App.

  6. Enter an App Name.

  7. Choose an app type under Select an App Type.

  8. Under Select Identity Providers, select an identity provider for your app. Internal User Store is the default.

    Note: When registering an externally hosted app, a Space Developer can choose from internal and external identity providers. If the Space Developer selects multiple identity providers, users must select which provider to use when they sign in. This option is available for all app types except Service-to-Service App.

    Select Identity Providers within dashboard

  9. If your App Type is Web App or Single-Page JavaScript App, under App Settings enter an allow list of URIs beneath Redirect URIs Whitelist. The redirect query parameter specified on the OAuth request must match the URIs specified in this list. Otherwise, Pivotal Single Sign‑On rejects the request. App Settings within dashboard

  10. Under Authorization, select the System Permissions that the app can request on the user’s behalf. If this app is only for authentication purposes, then the openid scope is sufficient. If the app makes API calls on behalf of the end user, specify both the scopes enforced by the API and the scopes to be requested by the app.

    Scope Description
    open Provides access to make OpenID Connect request. The default for Web, Native, and Single-Page JavaScript Apps
    user_attributes Provides access to custom attributes from an external identity provider
    roles Provides access to external groups from an identity provider
    uaa.resource Provides access to the check_token endpoint for service-to-service flows. The default for Service-to-Service Apps.

    Note: Add the user_attributes scope to the client scopes to return user attributes from the ID token.

    Note: Under Scopes, you can select resources defined in any space if the app type is a Web App, Native App, or Single-Page JavaScript App. If the app type is a Service-to-Service App, you can only select resources defined within the space.

  11. (Optional) Under Auto-Approved Scopes, select any scopes that Pivotal Single Sign‑On automatically approves when the app makes a request on behalf of a user. Select only scopes pertaining to apps owned and managed by your company. Do not select scopes that pertain to externally hosted apps.

  12. (Optional) Under Token Validity, change the token expiration times. The default is set in the configuration for the Pivotal Single Sign‑On service plan. For more information about tokens, see Configure a Token Policy.

  13. (Optional) If your App Type is a Web App or Single-Page JavaScript App, you can enable Show on Homepage to display the app on the UAA or Pivotal Account home page. If you want an app to display on the home page, you must enter an App Launch URL or upload an app icon.

    1. In App Launch URL, enter the address you want for your app.
    2. Upload an app icon for your app. Show on Homepage within dashboard
  14. Click Register App.

  15. View and download the App ID and App Secret. Record these credentials to use in other Pivotal Single Sign‑On procedures.

    Note: You can only view the App Secret when an app is first registered or the secret is regenerated.

  16. (Optional) If you want to view examples of how to integrate Pivotal Single Sign‑On into your Spring Boot apps, click Download Sample Apps. Download Sample Apps

Manage App Configurations

The SSO Developer Dashboard enables app developers to view the app configurations and resources available within their space.

Prerequisite

Before you access the dashboard, you must create a service instance for your space. See Create Service Instances.

Procedure

To manage your app configurations through the SSO Developer Dashboard:

  1. Log in to Apps Manager as a Space Developer.
  2. Select the space where your service instance is located.
  3. Under Services, click Manage next to the Pivotal Single Sign‑On service instance to launch the SSO Developer Dashboard.

    SSO Developer Dashboard View a larger version of this image.

  4. Click your app.

  5. Under Select Identity Providers, select an identity provider for your app. Internal User Store is the default.

    Note: When binding a Pivotal Platform app, a Space Developer can choose from internal and external identity providers. If the Space Developer selects multiple identity providers, users must select which provider to use when they sign in. This option is available for all app types except Service-to-Service App.

    Select Identity Providers within dashboard

  6. If your App Type is Web App or Single-Page JavaScript App, under App Settings enter an allow list of URIs beneath Redirect URIs Whitelist. The redirect query parameter specified on the OAuth request must match the URIs specified in this list. Otherwise, Pivotal Single Sign‑On rejects the request. App Settings within dashboard

  7. Under Authorization, select the System Permissions that the app can request on the user’s behalf. If this app is only for authentication purposes, then the openid scope is sufficient. If the app makes API calls on behalf of the end user, specify both the scopes enforced by the API and the scopes to be requested by the app.

    Scope Description
    open Provides access to make OpenID Connect request. The default for Web, Native, and Single-Page JavaScript Apps
    user_attributes Provides access to custom attributes from an external identity provider
    roles Provides access to external groups from an identity provider
    uaa.resource Provides access to the check_token endpoint for service-to-service flows. The default for Service-to-Service Apps.

    Note: Under Scopes, you can select resources defined in any space if the app type is a Web App, Native App, or Single-Page JavaScript App. If the app type is a Service-to-Service App, you can only select resources defined within the space.

  8. (Optional) Under Auto-Approved Scopes, select any scopes that Pivotal Single Sign‑On automatically approves when the app makes a request on behalf of a user. Select only scopes pertaining to apps owned and managed by your company. Do not select scopes that pertain to externally hosted apps.

  9. (Optional) Under Token Validity, change the token expiration times. The default is set in the configuration for the Pivotal Single Sign‑On service plan. For more information about tokens, see Configure a Token Policy.

  10. (Optional) If your App Type is a Web App or Single-Page JavaScript App, you can enable Show on Homepage to display the app on the UAA or Pivotal Account home page.

    Note: If you want an app to display on the home page, you must enter an App Launch URL or upload an app icon.

    1. In App Launch URL, enter the address you want for your app.
    2. Upload an app icon for your app. Show on Homepage within dashboard
  11. Click Update App.

Credentials of Existing App Configurations

You can view the credentials and endpoints required for app integration for an existing app on the Credentials page.

To view credentials of an existing app:

  1. Log in to Apps Manager as a Space Developer.
  2. Select the space where your service instance is located.
  3. Under Services, click the Pivotal Single Sign‑On service.
  4. Click Manage next to your Pivotal Single Sign‑On service instance to launch the SSO Developer Dashboard.
  5. Under Apps, click Credentials near the name of your app.

    Note: You can only view the App Secret when an app is first registered or the secret is regenerated.

    App credentials View a larger version of this image.

Regenerate an App Secret

Warning: You must not regenerate an app secret for Pivotal Platform bound apps, because VCAP_SERVICES does not update with the new client_secret. To regenerate a client for a Pivotal Platform bound app, you need to delete and re-create the service binding from your app to Pivotal Single Sign‑On.

To regenerate an app secret of an existing app:

  1. Log in to Apps Manager as a Space Developer.
  2. Select the space where your service instance is located.
  3. Under Services, click the Pivotal Single Sign‑On service.
  4. Click Manage next to your Pivotal Single Sign‑On service instance to launch the SSO Developer Dashboard.
  5. Under Apps, click the Credentials near the name of your app.
  6. Click Regenerate App secret under the App Secret field.
  7. On the pop-up, click Regenerate App Secret to confirm that you want to regenerate an app’s secret value.
  8. View and download the App ID and regenerated App Secret. Record these credentials to use in other Pivotal Single Sign‑On procedures.

    Note: Regenerating an App Secret requires you to update the secret at the client.

Create Admin Client

You can create an admin client to perform administrative functions, such as managing identity providers, apps, users, groups, and resources in a specific zone where you create the client.

You must be at least a plan admin to perform these steps.

To create an admin client:

  1. Log in to Apps Manager.
  2. Select the space where your service instance is located. This specifies the zone you manage as an admin client.
  3. Under Services, click the Pivotal Single Sign‑On service.
  4. Click Manage next to your Pivotal Single Sign‑On service instance to launch the SSO Developer Dashboard.
  5. Click Register App.
  6. Enter an App Name.
  7. Under Select an App Type, select Service-to-Service App.
  8. Under Authorization, select what actions the admin client can perform from the following Admin Permissions:

    Scope Description
    clients.admin Provides superuser access to create, modify, and delete clients
    clients.read Provides access to read information about clients
    clients.write Provides access to create and modify clients
    scim.create Provides access to create users
    scim.read Provides access to read information about users and group memberships
    scim.write Provides access to create, modify, and delete users and group memberships
    idps.read Provides access to read information about identity providers
    idps.write Provides access to create, modify, and delete identity providers

  9. Click Register App.

  10. View and download the App ID and App Secret. Record these credentials to use in other Pivotal Single Sign‑On procedures.

    Note: You can only view the App Secret when an app is first registered or the secret is regenerated.

Unregister App from Pivotal Single Sign‑On

To unregister an app from Pivotal Single Sign‑On:

Unregister a Pivotal Platform App

To unregister a Pivotal Platform app, run the following command:

cf unbind-service APP-NAME INSTANCE-NAME

Where:

  • APP-NAME is the name of your app.
  • INSTANCE-NAME is the name of the service instance you are binding.

For more information about the cf unbind-service command, see unbind-service in the Cloud Foundry CLI Reference Guide.

Note: If you delete a Pivotal Platform app, the app is automatically unregistered from Pivotal Single Sign‑On.

Unregister an Externally Hosted App Using Service Keys

To unregister an externally hosted app using service keys, run the following command:

cf delete-service-key INSTANCE-NAME SERVICE-KEY

Where:

  • INSTANCE-NAME is the name of your service instance.
  • SERVICE-KEY is the name you want for your service key.

For more information about the cf delete-service-key command, see delete-service-key in the Cloud Foundry CLI Reference Guide.

Unregister an Externally Hosted App Using SSO Developer Dashboard

To unregister an externally hosted app using the SSO Developer Dashboard:

  1. To navigate to the SSO Developer Dashboard, do the procedure in Access the SSO Developer Dashboard.
  2. Click your app.
  3. Click Unregister App at the bottom of the page.
  4. When prompted, click Unregister App to confirm that you want to unregister the app and its configurations.

    Note: Deleting an externally hosted app removes the app and its configurations from the SSO Developer Dashboard. However, it still exists on your hosted platform.