Configuring Apps

This topic explains how Pivotal Cloud Foundry (PCF) developers configure their apps to use the Single Sign-On (SSO) service and use the SSO Admin Client to manage connections between SSO identity providers, apps, users, and other resources.

Prerequisites for Registering Apps

Before you can register your app for SSO, you must create a service instance and choose your SSO application type as follows:

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

  2. Determine your app’s SSO application type. This informs which OAuth Grant Type you should use for your app. For more information, see Determining SSO 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 SSO service:

Register a PCF App

To configure SSO for a PCF app, use one of the following methods:

Configure SSO Properties with JSON Bind Parameters

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

To configure SSO 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 App Manager. For more information about binding service instances using Apps Manager, 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 Allowed grant type for the app through the SSO service. Only one grant type per app is supported by SSO. If you want to set more than one grant types per app, you can resort to this workaround.
identity_providers Allowed identity providers for the app through the SSO 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 the SSO service. 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 SSO service. Defaults to existing scopes/authorities
authorities Comma-separated list of authorities that belong to the app and are registered as client authorities with the SSO service. Privileged identity zone/plan admin scopes, such as scim.read, idps.write cannot be bootstrapped and must be assigned by zone/plan administrators. 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 the SSO service. 43200
refresh_token_lifetime Lifetime in seconds for the refresh token issued to the app by the SSO service. 2592000 (not used for client credentials)
resources Resources for the app to use as scopes/authorities for the SSO service 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 SSO Properties with the App Manifest

If you configure SSO properties with the app manifest, you do not need to manually bind your app to the service instance after you deploy your app. The SSO service 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 SSO service instance you want to bind your app. For an example, see the services section in the YAML sample below.
  2. Configure the SSO 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 SSO service instance and how to configure the GRANT_TYPE and SSO_IDENTITY_PROVIDERS SSO 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 SSO 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 SSO properties to include in the app manifest:

Property Name Description Default
name Name of the app n/a. This value is required.
GRANT_TYPE Allowed grant type for the app through the SSO service. Only one grant type per app is supported by SSO. If you want to set more than one grant types per app, you can use the workaround in Update Clients with UAAC. authorization_code(Web application type)
SSO_IDENTITY_PROVIDERS Allowed identity providers for the app through the SSO 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(PCF 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 the SSO service. 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 SSO service. (Defaults to existing scopes/authorities)
SSO_AUTHORITIES Comma-separated list of authorities that belong to the app and are registered as client authorities with the SSO service. Privileged identity zone and plan admin scopes, such as scim.read, idps.write cannot be bootstrapped and must be assigned by zone and plan administrators. 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 the SSO service. 43200
SSO_REFRESH_TOKEN_LIFETIME Lifetime in seconds for the refresh token issued to the app by the SSO service. 2592000 (not used for client credentials)
SSO_RESOURCES Resources that the app uses as scopes and authorities for the SSO service 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 application manifest. Currently you cannot specify additional permissions in the same top level permission, such as todo.admin, in additional application 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. (Application 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

Register an Externally Hosted App

To configure the SSO service for an externally hosted app, a non-PCF app, 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, do the following:

  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’s 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 SSO 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 Administrator 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, do the following:

  1. Determine the type of app for the SSO service.bind. For more information, see Determining SSO 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 SSO service instance. This launches the SSO Developer Dashboard.

    Sso dev dashboard apps View a larger version of this image.

  5. Click Register App.

  6. Enter an Application Name.

  7. Choose an app type under Select an Application 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.

    Sso dev select idp

  9. If your Application Type is Web App or Single-Page JavaScript App, under Application 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, SSO rejects the request. Sso dev redirect uri

  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 the SSO service 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 SSO service plan. For more information about tokens, see Configure a Token Policy.

  13. (Optional) If your Application 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. Sso dev show homepage
  14. Click Register App.

  15. View and download the App ID and App Secret. Record these credentials to use in other SSO 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 the SSO service into your Spring Boot Applications, click Download Sample Apps. Download sample apps

Manage App Configurations

The SSO Developer Dashboard allows 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 application configurations through the SSO Developer Dashboard, do the following:

  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 SSO service instance to launch the SSO Developer Dashboard.

    Sso dev dashboard apps 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 PCF 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 application types except Service-to-Service App.

    Sso dev select idp

  6. If your Application Type is Web App or Single-Page JavaScript App, under Application 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, SSO rejects the request. Sso dev redirect uri

  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 the SSO service 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 SSO service plan. For more information about tokens, see Configure a Token Policy.

  10. (Optional) If your Application 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. Sso dev show homepage
  11. Click Update App.

View Credentials of Existing App Configurations

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

To view credentials of an existing app, do the following:

  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 Single Sign-On service.
  4. Click Manage next to your SSO service instance to launch the SSO Developer Dashboard.
  5. Under Applications, click View 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.

    Sso dev creds View a larger version of this image.

Regenerate an App Secret

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

To regenerate an app secret of an existing app, do the following:

  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 Single Sign-On service.
  4. Click Manage next to your SSO service instance to launch the SSO Developer Dashboard.
  5. Under Applications, click the View 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 SSO 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, do the following:

  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 Single Sign-On service.
  4. Click Manage next to your SSO service instance to launch the SSO Developer Dashboard.
  5. Click Register App.
  6. Enter an Application Name.
  7. Under Select an Application 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 SSO procedures.

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

Unregister App from SSO

To unregister an app from SSO, do one of the following:

Unregister a PCF App

To unregister a PCF 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 PCF app, the app is automatically unregistered from SSO.

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 the SSO Developer Dashboard

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

  1. To navigate to the Service Instance Developer Dashboard, do the procedure in Access Service Instance Developer Dashboard.
  2. Click your app.
  3. Click Delete App at the bottom of the page.
  4. When prompted, click Delete App to confirm that you want to delete 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.