Using Pivotal Single Sign-On

Page last updated:

Pivotal Spring Cloud Gateway supports authentication and authorization using Pivotal Single Sign-On (Pivotal SSO). If you have installed Pivotal SSO, you can create a Pivotal SSO service plan for use by Pivotal Spring Cloud Gateway service instances.

Important: Ensure that the Pivotal SSO service plan is either enabled for all orgs or specifically enabled for the p-spring-cloud-gateway-service org.

When creating or updating a Spring Cloud Gateway service instance, you can enable SSO for the service instance by specifying the name of the Pivotal SSO service plan. When adding route configuration to a service instance, you can use parameters and custom filters provided by Pivotal Spring Cloud Gateway to incorporate single sign-on functionality for the route.

Configuring a Gateway Service Instance to Use Pivotal SSO

After creating a Pivotal SSO service plan to use with Pivotal Spring Cloud Gateway, you can use the sso.plan parameter passed to cf create-service or cf update-service to configure a Gateway service instance to use Pivotal SSO. The Gateway service broker will create a Pivotal SSO service instance for the Gateway service instance, using the specified Pivotal SSO plan.

To create a Gateway service instance which uses a Pivotal SSO service plan called gateway, you might run the following command:

$ cf create-service p.gateway standard my-gateway -c '{ "sso": { "plan": "my-sso-plan-for-gateway" } }'

To update an existing Gateway service instance so that it uses a Pivotal SSO service plan called gateway, you might run the following command:

$ cf update-service my-gateway -c '{ "sso": { "plan": "my-sso-plan-for-gateway" } }'

Setting Identity Provider

If you have configured one or more external identity providers for a Pivotal SSO service plan that you wish to use for a Pivotal Spring Cloud Gateway service instance, you can specify the identity providers using an sso.identity-providers parameter passed to cf create-service or cf update-service. This parameter is a JSON array containing a list of identity provider names configured in a Pivotal SSO service plan.

For example, if you have configured an external identity provider called google for the Pivotal SSO service plan called my-sso-plan-for-gateway, you can include this provider name in the configuration for a Gateway service instance using the following command:

$ cf create-service p.gateway standard my-gateway -c '{ "sso": { "plan": "my-sso-plan-for-gateway", "identity-providers": [ "google" ] } }'

Setting Roles Attribute Name

If you wish to use a custom attribute from the external identity provider as a role (see the Pivotal SSO documentation about custom attributes), you can set the sso.roles-user-attribute-name parameter. For example, if you have configured an external identity provider called okta for the Pivotal SSO service plan called my-sso-plan-for-gateway and you want to consider the value of the user attribute department along with the existing list of roles, you can set the sso.roles-user-attribute-name parameter to department as in the following command:

$ cf create-service p.gateway standard my-gateway -c '{ "sso": { "plan": "my-sso-plan-for-gateway", "identity-providers": [ "okta" ], "roles-user-attribute-name": "department" } }'

Setting Available Scopes

When creating or updating a Spring Cloud Gateway service instance, you can set the scopes that are available to be used in route configuration for the service instance, by using a scopes parameter passed to cf create-service or cf update-service. This parameter is a JSON array containing a list of scopes, which correspond to resource permissions configured in Pivotal SSO. (See the Pivotal SSO documentation about Managing Resources.)

To create a Gateway service instance that can use the menu.read and menu.write scopes, you might run the following command:

$ cf create-service p.gateway standard my-gateway -c '{ "sso": { "plan": "my-sso-plan-for-gateway", "scopes": ["menu.read", "menu.write"] } }'

Using Pivotal SSO in Route Configuration

See the following sections for information about providing route configuration that uses Pivotal SSO. This requires a Pivotal Spring Cloud Gateway service instance which has been configured to use a Pivotal SSO service plan (see Configuring a Gateway Service Instance to Use Pivotal SSO).

Redirecting to Pivotal SSO for Login Flow

To cause a Pivotal Spring Cloud Gateway service instance route to incorporate a login flow using the Gateway service instance’s associated Pivotal SSO service instance, you can set the sso-enabled parameter to true, which will enable the dedicated SsoLogin filter. You can set this parameter in the route JSON object given to the cf bind-service, cf create-service, or cf create update-service commands.

For instance, to bind an app called greeter to a Gateway service instance, adding one route for the app and redirecting the route’s requests to Pivotal SSO to provide a login flow, you might run the following command:

$ cf bind-service greeter my-gateway -c '{"routes": [ {"path": "/greeting/**",
    "sso-enabled": true} ] }'

You can also manually add the SsoLogin filter by including it in the list of filters in the JSON object for the route:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["SsoLogin"] } ] }'

Specifying Required Roles With the Roles Filter

The Roles filter uses Pivotal SSO to restrict access to a route, so that only users with the specified roles can access the route.

When adding a route to a Gateway service instance, you can set the sso-enabled parameter to true and add the dedicated roles filter by setting the roles parameter in the JSON object for the route. This parameter should list the roles that are allowed to access the route. You can include it in the route’s JSON object given to the cf bind-service, cf create-service, or cf create update-service commands.

For example, to bind an app called cook to a Gateway service instance, adding one route for the app, redirecting the route’s requests to Pivotal SSO to provide a login flow, and restricting access to users with the ADMIN role, you might run the following command:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "sso-enabled": true, "roles": ["ADMIN"] } ] }'

If the roles parameter is set for a route, the Gateway service instance uses the Roles filter (with the provided list of roles) for that route.

You can also manually add the Roles filter by including it in the list of filters in the JSON object for the route:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "sso-enabled": true, "filters": ["Roles=ADMIN"] } ] }'

Configuring Requested Scopes for an App

To cause an app to request permission scopes for a resource when authenticating a user using Pivotal Spring Cloud Gateway and Pivotal SSO, you can set the sso-enabled parameter to true and add the dedicated Scopes filter by setting the scopes parameter in the JSON object for the route. This parameter should list the scopes that the app will request. You can include it in the route’s JSON object given to the cf bind-service, cf create-service, or cf create update-service commands.

For instance, to bind an app called greeter to a Gateway service instance, adding one route for the app, redirecting the route’s requests to Pivotal SSO to provide a login flow, and requesting the greeting.read scope, you might run the following command:

$ cf bind-service greeter my-gateway -c '{"routes": [ {"path": "/greeting/**",
    "sso-enabled": true, "scopes": ["greeting.read"] } ] }'

When a user is authenticated through Pivotal SSO while reaching the app through the Gateway service instance, the Pivotal SSO service instance will present a page requesting the user to grant access to the greeting.read scope for the app. The user can then authorize or deny this scope for the app.

If the scopes parameter is set for a route, the Gateway service instance uses the Scopes filter (with the provided list of scopes to request) for that route.

You can also manually add the Scopes filter by including it in the list of filters in the JSON object for the route:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**",
    "sso-enabled": true, "filters": ["Scopes=menu.read"] } ] }'

Passing User Identity Token to an App With the TokenRelay Filter

The TokenRelay filter uses Pivotal SSO to pass a currently-authenticated user’s identity token to the app when the user accesses the app’s route.

When adding a route to a Gateway service instance, you can add the TokenRelay filter by setting the token-relay parameter in the JSON object for the route. For example, when binding an app called “cook” to a Gateway service instance, you can add a route for the app and set token-relay to true for that route:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "sso-enabled": true, "token-relay": true } ] }'

If the token-relay parameter is set to true for a route, the Gateway service instance uses the TokenRelay filter for that route.

You can also manually add the TokenRelay filter by including it in the list of filters in the JSON object for the route:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["SsoLogin", "TokenRelay"] } ] }'