LATEST VERSION: 1.7 - RELEASE NOTES
Single Sign-On v1.7

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.

Set Up PCF Apps to Use SSO

To configure SSO for an app running internally on PCF, do the following:

  1. Determine the SSO application type of the app to use the SSO service. For information, see Determining SSO Application Type.

  2. Configure the SSO service for the app using one of the following methods:

    Note: Use either bind parameters or environment variables to configure SSO properties. Apps that have environment variables set do not work with bind parameters.

Option 1: Configure SSO Properties with JSON Bind Parameters

In SSO v1.7.0 and later, you can use a JSON string containing bind parameters to configure SSO properties. To do this, bind the SSO service using the cf bind-service command and include the -c flag followed by the JSON string. For more information about bind parameters, see Bind Parameter Options below.

For example:

$ cf bind-service my-app my-instance \
    -c '{"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 this command, see bind-service in the Cloud Foundry CLI Reference Guide.

Bind Parameter Options

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 wish 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 whitelist 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 administrator 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 in order 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

For more information and bind parameter examples, see the identity-sample-apps GitHub repository.

Option 2: Configure SSO Properties with Environment Variables

Instead of using bind parameters, you can manually configure your SSO service for the app using environment variables, then bind the app to an SSO service instance.

Note: This step is not necessary if you have already configured SSO properties with your app using bind parameters. Apps that have environment variables set do not work with bind parameters and an error is shown.

The SSO service reads its configuration properties from environment variables that are set in the apps that use it. Most of these environment variables are prefixed with SSO_.

There are two ways to set the SSO configuration properties for an app:

  • Set the environment variables manually after you deploy the app, in Apps Manager or with the Cloud Foundry Command-Line Interface (cf CLI).

  • Include the config settings in the application manifest, so that PCF bootstraps them automatically when it deploys the app.

The table below provides descriptions and default values for environment variables that apps use to configure SSO. See the SSO sample apps for details and the manifest.yml files in the same repository for examples of bootstrapping these values.

Note: These configurations are only applied when initially binding to the service instance. A subsequent cf push of the app does not update the configurations. To update these configurations, manually update them using the SSO dashboard, or unbind and rebind the service instance.

Property Name Description Default
name Name of the app (N/A - Required Value)
GRANT_TYPE Allowed grant type for the app through the SSO service. Only one grant type per app is supported by SSO. If you wish to set more than one grant types per app, you can resort to this workaround.
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
SSO_REDIRECT_URIS Comma separated whitelist 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)
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. 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/plan administrator 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
SSO_REQUIRED_USER_GROUPS Comma-separated list of groups a user must have in order 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 will use as scopes/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. Note that 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 will be displayed next to the app name on the Pivotal Account dashboard if show on home page is enabled. Do not exceed 64kb. (No value)
SSO_LAUNCH_URL App launch URL that will be used for the app on the Pivotal Account dashboard if show on home page is enabled. (Application route)
SSO_SHOW_ON_HOME_PAGE If set to true, the app will appear on the Pivotal Account dashboard with the corresponding icon and launch URL. True

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

Remove SSO Configuration Properties

You can remove SSO configuration properties for an app, or any environment variables set through cf set-env, Apps Manager, or bootstrapping as follows:

  1. Run cf unset-env APP_NAME PROPERTY_NAME.

  2. Rebind the app.

Manually Configure Apps for SSO

For apps already deployed to PCF, you can set their GRANT_TYPE, SSO_IDENTITY_PROVIDERS, and other SSO configuration environment variables with the cf set-env command, or in Apps Manager as follows:

  1. Log in to Apps Manager at https://apps.YOUR-SYSTEM-DOMAIN.

  2. Navigate to your app.

  3. Click the Env Variables tab.

  4. Click Add an Env Variable.

  5. For Variable Name enter the name of the SSO configuration property that you are setting, such as GRANT_TYPE.

  6. For Value, enter the property value. For example, to set the GRANT_TYPE property for a Single-Page JavaScript App, enter implicit, which is the OAuth Grant Type listed for your SSO application type above.

  7. Bind and restage your app.

Bootstrap SSO Configuration

In SSO v1.4.0 and later, you can include SSO configuration properties in your application manifest, to automatically bootstrap the values when you bind or rebind the app to an SSO service instance.

The values from the manifest automatically save to the environment variables that configure your app for SSO. Bootstrapping SSO configuration values from the manifest eliminates the need to set environment variables after you deploy your app.

Note: These configurations are only applied at the initial service binding time. Subsequent cf push of the application will NOT update the configurations. You will either need to manually update the configurations via the SSO dashboard or unbind and rebind the service instance.

This snippet below shows how to include GRANT_TYPE SSO_IDENTITY_PROVIDERS in your manifest.

---
applications:
  - name: APPLICATION NAME
    env:
      GRANT_TYPE: password
      SSO_IDENTITY_PROVIDERS: uaa, sample-identity-provider

The GRANT_TYPE property defaults to authorization_code, for Web App application type. SSO_IDENTITY_PROVIDERS defaults to uaa, for the PCF internal user store.

If you specify your own scopes and authorities, consider including the following values in your SSO_SCOPES or SSO_AUTHORITIES property list. These values are not added your user-provided list by default:

  • openid — for apps with authorization code, password, and implicit grant type
  • uaa.resource — for apps with client_credentials grant type

The table below lists all SSO properties that you can set in your application manifest to bootstrap the values into your app’s SSO client configuration.

After an app deploys with bootstrapped SSO configuration values, it is ready to bind to an SSO service instance.

Bind a PCF App

After a PCF app is configured for SSO, you can bind it to an SSO service instance using Apps Manager as follows:

  1. Log in to Apps Manager as a Space Developer.
  2. Select the space where your app runs.
  3. Under Applications, click the name of your app.
  4. Click the Services tab.
  5. Click Bind a Service.
  6. Bind your app to a service to create an associated OAuth Client.
    1. Select an existing SSO service instance from the drop-down menu and click Bind.
    2. Create a new service instance:
      1. Click or add from Marketplace.
      2. Select the Single Sign-On service under Services Marketplace.
      3. Select a Service Plan, then click Select this plan.
      4. Enter an Instance Name, select a space, select an app, then click Add.

Alternatively, you can bind the PCF app to an SSO service instance using cf CLI as follows:

 cf bind-service APP-NAME SAMPLE-PLAN-SERVICE-INSTANCE

Manage App Configurations Using the SSO Dashboard

The SSO dashboard allows application developers to view the app configurations and resources available within their space. To access the dashboard, first you must create a service instance for your Space. Then you can follow the steps below to manage your application configurations via the SSO 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 SSO service instance to launch the SSO dashboard.
  4. Click your app.
  5. Specify a value in the App Launch URL field that you want to set as the address of your app.
  6. Upload an app icon for your app.
  7. Click Show on homepage to display the app on the UAA or Pivotal Account home page.

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

  8. Select one or more Identity Providers 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.

  9. If your Application Type is Web App or Single-Page JavaScript App, enter a whitelist of Auth Redirect URIs beneath Redirect URIs. The redirect query parameter specified on the OAuth request must match the URIs specified in this list. Otherwise, SSO rejects the request.
  10. For the Scopes field, specify the permissions that the app can request on the user’s behalf. This field defaults to openid for Web, Native Mobile, and Single-Page JavaScript Apps. This field defaults to uaa.resource for Service-to-Service Apps. If this app is purely 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
    openid Provides access to make OpenID Connect requests
    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

    Note: Under Scopes, you can select resources defined in any space if the app type is a Web App, Native Mobile 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. For 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 apps external to PCF.

  12. Click Save Config. The Next Steps page appears, describing the endpoints required for app integration. For more information, see Integrate SSO with Your App.

Register an External App Using Service Keys

Note: The service key feature was introduced in v1.7. If you are using v1.6 or earlier, select that documentation version from the dropdown at the top of this page.

To register an external app using service keys, use the create-service-key command with -c flag followed by a JSON string containing a set of config parameters.

The create-service-key command accepts all bind-service config options. Use the name parameter to define the external app’s name.

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

For example:

$ cf create-service-key my-instance my-service-key \
    -c '{"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 a full list of bind parameters accepted, refer to the bind parameters section. The only additional value which is required for service keys is the name parameter that should include the user-defined name of the app.

After you create the service key for your external app, run the following command to retrieve the service key’s credentials:

cf service-key SERVICE_INSTANCE SERVICE_KEY_NAME

For more information about how to use these values, see Integrate SSO with Your App. Also notice that for client_credentials grant types, administrative scopes and scopes in other spaces are not available and must be manually added by a plan administrator or system operator via the dashboard or UAA CLI.

Register an External App Using the SSO Dashboard

Register an app external to PCF using the SSO Developer Dashboard. To register an external app, see the following steps:

  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 dashboard.
  5. Click New App.
  6. Enter an App Name.
  7. Choose an app type under Select an Application Type.
  8. Enter an App Launch URL that specifies the address of your app.
  9. Upload an app icon for your app.
  10. Click Show on homepage to display the app on the UAA or Pivotal Account home page.

    Note: To display the app on the home page, you must enter an App Launch URL or Upload an app icon.

  11. Select one or more Identity Providers 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.

  12. If your Application Type is Web App or Single-Page JavaScript App, enter a whitelist of Auth Redirect URIs beneath Redirect URIs. The redirect query parameter specified on the OAuth request must match the URIs specified in this list. Otherwise, SSO rejects the request.
  13. For the Scopes field, specify the permissions that the app can request on the user’s behalf. This field defaults to openid for Web, Native Mobile, and Single-Page JavaScript Apps. This field defaults to uaa.resource for Service-to-Service Apps. If this app is purely for authentication purposes, then the openid scope is sufficient. If the app makes API calls on behalf of the end user, you must specify both the scopes enforced by the API and the scopes to be requested by the app.

    Scope Description
    openid Provides access to make OpenID Connect requests
    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 check_token endpoint for service-to-service flows

    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 Mobile 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.

  14. For 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 apps external to PCF.

  15. Click Create App. The Next Steps page appears, describing the endpoints required for app integration. For more information, see Integrate SSO with Your App.

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 administrator 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 Single Sign-On service.
  4. Click Manage next to your SSO service instance to launch the SSO dashboard.
  5. Click New App.
  6. Enter an App Name.
  7. Under Select an Application Type, select Service-to-Service App.
  8. Click Select Scopes and choose 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 Create App. You are given the option to view and download the App ID and App Secret. Download or make note of this information for use with other SSO procedures.

Delete App that Uses SSO

Delete a PCF app or an external app that uses SSO as follows:

Delete a PCF App

To delete an app hosted on PCF:

  1. Log in to Apps Manager as a Space Developer.
  2. Select the space where your app is located.
  3. Under Applications, click the name of your app.
  4. On the Application page, click Delete App.
  5. On the popup, click Delete to confirm that you want to delete the app and its configurations from Apps Manager and the service dashboard.

Delete an External App

To delete an external app that uses SSO:

  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 your SSO service instance to launch the SSO dashboard.
  4. Click your app.
  5. Click Delete at the bottom of the page.
  6. On the popup, click Delete App to confirm that you want to delete the app and its configurations.

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

Create a pull request or raise an issue on the source for this page in GitHub