Spring Cloud Gateway for VMware Tanzu supports authentication and authorization using the Single Sign-On for VMware Tanzu tile. If you have installed this tile, you can create a Single sign-on for VMware Tanzu service plan for use by Spring Cloud Gateway service instances.
Important: Ensure that the Single Sign-On for VMware Tanzu service plan is either activated for all orgs or specifically activated for the p-spring-cloud-gateway-service org.
When creating or updating a Spring Cloud Gateway service instance, you can activate SSO for the service instance by specifying the name of the Single Sign-On for VMware Tanzu service plan. When adding route configuration to a service instance, you can use parameters and custom filters provided by Spring Cloud Gateway for VMware Tanzu to incorporate single sign-on functionality for the route.
In Spring Cloud Gateway for VMware Tanzu v1.0.3 and later, the Gateway's authentication session is distinct from client app authentication sessions. If your client app uses Spring Security and Spring Session, its session will be unaffected by a user logging in or logging out through the Gateway and Single Sign-On for VMware Tanzu.
Configuring a Gateway service instance to use single sign-on for VMware Tanzu
After creating a Single Sign-On for VMware Tanzu service plan to use with Spring Cloud Gateway for VMware Tanzu, you can use the sso.plan parameter passed to cf create-service or cf update-service to configure a Gateway service instance to use Single Sign-On for VMware Tanzu. The Gateway service broker will create a Single Sign-On for VMware Tanzu service instance for the Gateway service instance, using the specified Single Sign-On for VMware Tanzu plan.
To create a Gateway service instance that uses a Single Sign-On for VMware Tanzu service plan called my-sso-plan-for-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 Single Sign-On for VMware Tanzu service plan called my-sso-plan-for-gateway, you might run the following command:
$ cf update-service my-gateway -c '{ "sso": { "plan": "my-sso-plan-for-gateway" } }'
Important: Updating a gateway instance from using one SSO plan to another will result in downtime. And if a gateway bound app receives SSO credentials through gateway binding credentials, then a rebind is required for the bound app to received the most recent SSO credentials.
Setting identity provider
If you have configured one or more external identity providers for a Single Sign-On for VMware Tanzu service plan that you wish to use for a Spring Cloud Gateway for VMware Tanzu 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 Single Sign-On for VMware Tanzu service plan.
For example, if you have configured an identity provider with originKey value of google activated for the Single Sign-On for VMware Tanzu service plan called my-sso-plan-for-gateway, you can include this identity provider 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 Single Sign-On for VMware Tanzu 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 Single Sign-On for VMware Tanzu 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 Single Sign-On for VMware Tanzu. (See the Single Sign-On for VMware Tanzu 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 single sign-on for VMware Tanzu in route configuration
See the following sections for information about providing route configuration that uses Single Sign-On for VMware Tanzu. This requires a Spring Cloud Gateway for VMware Tanzu service instance which has been configured to use a Single Sign-On for VMware Tanzu service plan (see Configuring a Gateway Service Instance to Use Single Sign-On for VMware Tanzu).
Redirecting to single sign-on for VMware Tanzu for login flow
To cause a Spring Cloud Gateway for VMware Tanzu service instance route to incorporate a login flow using the Gateway service instance's associated Single Sign-On for VMware Tanzu service instance, you can set the sso-enabled parameter to true, which will activate 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 Single Sign-On for VMware Tanzu 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 Single Sign-On for VMware Tanzu 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 Single Sign-On for VMware Tanzu 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 Spring Cloud Gateway for VMware Tanzu and Single Sign-On for VMware Tanzu, 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 Single Sign-On for VMware Tanzu 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 Single Sign-On for VMware Tanzu while reaching the app through the Gateway service instance, the Single Sign-On for VMware Tanzu 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"] } ] }'
Defining scopes required by an app
An app that receives traffic through a Spring Cloud Gateway for VMware Tanzu service instance and permits SSO should request all scopes that the app itself requires, as well as any scopes that are required by APIs which the app uses.
For example, an order app may provide APIs through a Gateway service instance, using the following route configuration:
{
"routes": [
{
"path": "/history",
"sso-enabled": true,
"scopes": [
"order.history"
]
},
{
"path": "/order/**",
"sso-enabled": true,
"scopes": [
"order.read"
]
}
]
}
If a front-end app then calls the history and order APIs, that front-end app should request all scopes required by those APIs--in this case, the order.history and order.read scopes. You might bind the front-end app to the Gateway service instance using the following route configuration:
{
"routes": [
{
"path": "/**",
"sso-enabled": true,
"scopes": [
"order.read",
"order.history"
]
}
]
}
Passing user identity token to an app With the TokenRelay filter
The TokenRelay filter uses Single Sign-On for VMware Tanzu 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"] } ] }'
Log out
Spring Cloud Gateway for VMware Tanzu service instances provide a default API endpoint to log out of the current SSO session. The path to this endpoint is /scg-logout. There are two different outcomes that can be accomplished depending on how the log out endpoint is called: log out of session and redirect to UAA log out or only log out the service instance session.
Log out of UAA and SSO session
Sending a GET request to the /scg-logout endpoint then it will send a 302 redirect response to the UAA log out URL. In order for user to be returned back to a path on the Gateway service instance, you can add a redirect parameter to the GET /scg-logout request. For example, if a user goes to ${gatewayUrl}/scg-logout?redirect=/home in their browser they will be redirected back to ${gatewayUrl}/home after logging out of UAA.
Important: The value of the redirect parameter is a valid path on the Gateway service instance. You cannot redirect to an external URL.
Only log out SSO session
If the GET request to the /scg-logout is sent using a XMLHttpRequest (XHR), then the 302 redirect could be swallowed and not handled in the response handler. In this case, the user would only be logged out of the SSO session on the Gateway service instance and would still have a valid UAA session. The behavior typically seen in this case is that if the user attempts to login again they are automatically sent back to gateway as authenticated from UAA.
