Understanding UAA and OAuth2 Access Token Flows

When you use the authorization code grant type, the client directs the resource owner to UAA, which in turn directs the resource owner back to the client with the authorization code. The OAuth2 endpoint in UAA accepts authorization code to provide an Access Token.

When you use the Authorization Code grant type, the token is stored and managed on the server’s side. Therefore any technical information present in the token (such as scope names), is not leaked to the user and the token is less prone to be misused. Additionally, with Authorization Code grant type, it is easier to terminate a user’s session without waiting for the token to expire its lifetime. Authorization Code security relies on a robust session management scheme that includes best practices such as HTTP protocol hardening using HTTP security headers, HTTP Cookie security flags, adequate session lifetime, and secure session termination (sign-out mechanism).

For more details on the Authorization Grant type, see RFC 6749.

The following diagram shows the high-level flow for obtaining access tokens using authorization grant.

1. The client requests access to a resource. The request includes client identifier, requested scope, local state, and a redirection URI.
2. UAA authenticates the resource owner (via the user-agent) and establishes whether the resource owner grants or denies the client's access request.
3. If the resource owner grants access, UAA sends the authorization code back to the client using the redirection URI provided in previous step.
4. The client requests an access token from the UAA token endpoint by including the authorization code received in the previous step.
5. UAA authenticates the client, validates the authorization code, and ensures that the redirection URI received matches the URI used to redirect the client. If the client is authenticated, UAA sends an access token back.

For detailed information on UAA endpoints used to generate authorization code and Access Tokens, see open-source UAA documentation.

When you use the implicit grant type, UAA directly issues an Access Token to the client without authenticating the client. This reduces the number of round trips required to obtain an access token. However with this grant type, the access token is transmitted in the URI fragment, which can expose it to unauthorized parties. Additionally if the public clients use implicit flows, UAA cannot determine what client an access token was issued to.

The benefit of using implicit grants is that it improve the responsiveness and efficiency of some clients (for example, a client implemented as an in-browser application). However, you must weigh this benefit against the security implications of using implicit grants.

For more details on the Implicit Grant type, see RFC 6749.

The following diagram shows the high-level flow for obtaining access tokens using implicit grant type.

1. The client sends a request to the authorization endpoint in UAA. The request includes client identifier, requested scope, local state, and a redirection URI. Redirection URI is required for UAA to send the Access Token.
2. UAA authenticates the resource owner and establishes whether the resource owner grants or denies the client's access request.
3. If the resource owner grants access, UAA redirects the user-agent back to the client using the redirection URI specified in step 1. The redirection URI includes the access token in the URI fragment.
4. The user-agent makes a request to the web-hosted client resource. The user-agent does not pass the URI fragment information to the client resource.
5. The web-hosted client resource returns a web page that can access the full redirection URI including the URI fragment retained by the user-agent, and can extract the access token contained in the URI fragment.
6. The user-agent extracts the access token. Often extraction includes executing the script provided by the web-hosted client resource locally.
7. The user-agent passes the access token to the client.

For detailed information on UAA endpoints used to generate Access Tokens with implicit grant type, see open-source UAA documentation.

When you use the resource owner password credentials grant type, the OAuth2 endpoint in UAA accepts the username and password and provides Access Tokens.

You must use this grant type only when there is a high degree of trust between the resource owner and the client (for example, the client is part of the device operating system or a highly privileged application), and when other authorization grant types such as an authorization code are not available.

When you use this grant type, the client does not need to store the resource owner credentials for future use. The client simply exchanges the credentials with a long-lived access token or refresh token.

For more details on resource owner password credentials grant type, see RFC 6749.

The following diagram shows the high-level flow for obtaining access tokens using resource owner password credentials grant.

1. The resource owner provides its username and password to the client.
2. The client includes the credentials in the requests for an access token from UAA token endpoint.
3. UAA authenticates the client and validates the resource owner credentials, and if valid, issues an access token.

For detailed information on UAA endpoints used to generate Access Tokens, see open-source UAA documentation.

When you use the client credentials grant type, the OAuth2 endpoint in UAA accepts the client id and client secret and provides Access Tokens.

The client credentials can be used when the authorization scope is limited to the protected resources under the control of the client, or to protected resources previously authorized with UAA. Client credentials authorization grant is typically used when the client is acting on its own behalf (the client is also the resource owner) or is requesting access to protected resources based on previous authorization with UAA.

For more details on the Authorization Grant type, see RFC 6749.

The following diagram shows the high-level flow for obtaining access tokens using client credentials grant.

1. The client requests an access token from the token endpoint.
2. UAA authenticates the client, and if valid, issues an access token.

For detailed information on UAA endpoints used to generate Access Tokens with client credentials grant, see open-source UAA documentation.