Configure Applications

Pivotal Web Services End of Availability Announced
For more information, see Frequently Asked Questions.

This topic explains how Pivotal Web Services (PWS) developers configure their apps to use the Single Sign-On (SSO) service, write SSO integration into their apps, and use the SSO Admin Client to manage connections between SSO identity providers, apps, users and other resources.

Determine Your SSO Application Type

Before you bind or register an app, you must determine its SSO application type and the corresponding OAuth grant type.

If your app authenticates end users, its application type is Web App, Native Mobile App, or Single-Page JavaScript App. If the app does not authenticate end users, but rather accesses other services or APIs on its own behalf, then its type is Service-to-Service App.

See the table below to determine your app’s SSO Application Type and OAuth Grant Type:

Note: The Native Mobile App application type is intended only for highly-trusted apps such as company-owned and managed apps.

Set Up PWS Apps to Use SSO

To configure SSO for an app running internally on PWS, you first need to determine the SSO application type of the app that will use the SSO service.

Then you configure your SSO service for the app using environment variables and bind the app to an SSO service instance. These steps are described below.

Configure SSO Properties

The SSO service reads its configuration properties from environment variables that are set in the apps that use it. To enable a PWS-hosted app to bind to an SSO service instance, you must set the following environment variables:

• GRANT_TYPE — the type of OAuth authentication associated with the SSO Application Type in the table above.
• SSO_IDENTITY_PROVIDERS — the internal or external identity provider(s) for the app to use.

You can set additional environment variables to further configure how an app uses SSO, as described below. 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 PWS bootstraps them automatically when it deploys the app.

Manually Configure Apps for SSO

For apps already deployed to PWS, 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://console.run.pivotal.io.

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, userstore.example.com
    

The GRANT_TYPE property defaults to authorization_code, for Web App application type. SSO_IDENTITY_PROVIDERS defaults to uaa, for the PWS 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.

SSO Configuration Properties

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

Additional information and manifest examples are available on the identity sample apps.

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.

Bind a PWS App

After a PWS app is configured for SSO, you can bind it to an SSO service instance 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.
7. Click Manage under the SSO service instance to launch the SSO dashboard.
8. Click your app.
9. Specify a value in the App Launch URL field that you want to set as the address of your app.
10. Upload an app icon for your app.
11. 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.

12. Select one or more Identity Providers for your app. Internal User Store is the default.

    Note: When binding a PWS 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.

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

14. 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 application type is a Web App, Native Mobile App, or Single-Page JavaScript App. If the application type is a Service-to-Service App, you can only select resources defined within the space.

1. 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 PWS.
2. Click Save Config. The Next Steps page appears, describing the endpoints required for app integration. For more information, see Integrate SSO with Apps below.

Manage App Configurations via 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. This launches the SSO dashboard.

Register an External App

1. Determine the type of the app that will use the SSO service.

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 application 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 application type is a Web App, Native Mobile App, or Single-Page JavaScript App. If the application 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 PWS.

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

Integrate SSO with an App

Because SSO service is based on the OAuth protocol, any app that uses SSO must be OAuth-aware.

Java Apps

If you are using Java, see Single Sign-On Service Sample Applications. These are sample apps created using Spring Boot for all four application types. These apps use the SSO Service Connector, which auto-configures the app for OAuth. After binding the app to an SSO service instance, you must restart the app for the new SSO configuration to take effect.

Non-Java Apps

To configure non-Java apps for OAuth, supply the following properties as environment variables to your app after the SSO service bind. You can view this information on the Next Steps page of the SSO dashboard.

• App ID, also known as OAuth Client ID
• App Secret, also known as OAuth Client Secret
• OAuth Authorization URL, the endpoint for client authorization
• OAuth Token URL, the endpoint for token retrieval

To validate the token, you must verify the following:

1. The token is a properly signed JSON Web Token with an appropriate public key. The key can be downloaded from the Token Verification Key endpoint specified on the Next Steps page.

2. The value of aud in the token matches your App ID.

3. The value of iss matches https://AUTH-DOMAIN.uaa.run.pivotal.io/oauth/token.

4. The expiry time of the token, exp, has not passed.

Create Admin Client

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

Create an admin client as follows:

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.

Delete App that Uses SSO

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

Delete a PWS App

To delete an app hosted on PWS:

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 PWS removes the app and its configurations from the SSO dashboard. However, it still exists on your hosted platform.