LATEST VERSION: 1.3 - CHANGELOG
Single Sign-On v1.3

Configure Applications

This topic describes how Space Developers bind internal applications or register external applications to their Single Sign-On (SSO) service instances.

If your application is hosted on Pivotal Cloud Foundry (PCF), refer to the Bind an Application Hosted on PCF section to bind the application to your SSO service instance from Apps Manager. If your application is externally hosted, refer to the Register an External Application section to register your application with your SSO service instance from the SSO dashboard.

When you bind or register an application with a SSO service instance, SSO creates an OAuth client. This OAuth client acts as an OAuth 2.0 authorization server and issues tokens.

Determine Your Application Type

Before you bind or register an application, you must know your SSO application type. Refer to the table below to determine the application type best suited for your application.

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

Application Type SSO Application Type OAuth Grant Type Equivalent
Web Web App authorization code
Native Mobile, Desktop, or Command Line Native Mobile App password (the resource owner’s password)
Service-to-Service Service-to-Service App client_credentials
Single-Page JavaScript Single-Page JavaScript App implicit

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

Preconfigure an Application Hosted on PCF

Follow the steps below to create environment variables that you can then set during a bind.

Set Application Type:

  • Option 1: Set the grant type environment variable by performing the following steps:

    1. Log in to Apps Manager at https://apps.YOUR-SYSTEM-DOMAIN.
    2. Navigate to your application.
    3. Click the Env Variables tab.
    4. Click Add an Env Variable.
    5. For Variable Name, enter GRANT_TYPE.
    6. For Value, enter the OAuth grant type for your application type. For example, if your application is a Single-Page JavaScript App, specify implicit.
    7. Bind and restage your application.
  • Option 2: Set the grant type environment variable by including the following in your application manifest. If you choose this option, you do not have to configure environment variables after deploying your app.

    ---
    applications:
        - name: APPLICATION NAME
          env:
              GRANT_TYPE: OAUTH GRANT TYPE
    

    Note: If you do not provide a GRANT_TYPE, the application type defaults to Web App.

Set Identity Provider:

Set the identity providers by including the following in your application manifest:

---
applications:
    - name: APPLICATION NAME
      env:
          SSO_IDENTITY_PROVIDERS: COMMA SEPARATED LIST OF IDENTITY PROVIDERS

Note: If you do not provide any SSO_IDENTITY_PROVIDERS, the internal user store will be selected by default.

Bind an Application Hosted on PCF

  1. Log in to Apps Manager as a Space Developer.
  2. Select the space where your application runs.
  3. Under Applications, click the name of your application.
  4. Click the Services tab.
  5. Click Bind a Service.
  6. Bind your application to a service to create an associated OAuth Client.
    1. Select an existing SSO service instance from the dropdown 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 application.
  9. Specify a value in the App Launch URL field that you want to set as the address of your application.
  10. Upload an app icon for your application.
  11. Click Show on homepage to display the application on the UAA or Pivotal Account home page.

    Note: If you would like application 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 application. Internal User Store is the default.

    Note: When registering an externally hosted application, 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 application 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 application is purely for authentication purposes, then the openid scope is sufficient. If the application 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 application.

    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.

  15. 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 applications owned and managed by your company. Do not select scopes that pertain to applications external to PCF.

  16. Click Save Config. The Next Steps page appears, describing the endpoints required for application integration. Refer to the Integrate SSO with Applications section below for more details.

Register an External Application

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

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

  10. Select one or more Identity Providers for your application. Internal User Store is the default.

    Note: When registering an externally hosted application, 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.

  11. 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.
  12. For the Scopes field, specify the permissions that the application 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 application is purely for authentication purposes, then the openid scope is sufficient. If the application 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 application.

    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.

  13. 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 applications owned and managed by your company. Do not select scopes that pertain to applications external to PCF.

  14. Click Create App. The Next Steps page appears, describing the endpoints required for application integration. Refer to the Integrate SSO with Applications section below for more details.

Integrate SSO with Applications

Because SSO service is based on the OAuth protocol, your applications must be OAuth-aware.

Java Applications

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

Non-Java Applications

To configure non-Java applications for OAuth, supply the following properties as environment variables to your application 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.YOUR-SYSTEM-DOMAIN/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, applications, users, groups, and resources in a specific zone where you create the client.

To create an admin client, complete the following steps:

  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 Application

Complete the procedure that corresponds with your application type.

Delete a PCF Application

To delete an application hosted on PCF, complete the following steps:

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

Delete an External Application

To delete an external application not hosted on PCF, complete the following steps:

  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 application.
  5. Click Delete at the bottom of the page.
  6. On the popup, click Delete App to confirm that you want to delete the application and its configurations.

    Note: Deleting an externally hosted application removes the application 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