View on GitHub

AAC

Call Your API on behalf of a User

When you call your API on behalf of the user, it is necessary to provide the access token that is associated to the client application and to the user in order to validate the access and perform specific authorization operations. Such should be obtained upon successful user authentication following e.g., the OAuth2.0 Authorization Code Flow.

Overview

In this scenario the API will receive a call with the access token included. In particular

  1. An app authenticates the user with AAC following OAuth2.0 / OpenID Connect protocols;
  2. AAC provides the app with access token (and potentially refresh token and ID token);
  3. The app calls the API providing the access token with the request;
  4. The API validates the access token;
  5. The API responds with the requested info.

Implementation

1. Client Configuration for Authentication

To have this scenario implemented it is necessary to start with the configuration of the client application with the necessary scopes and properties. See here for more details about this scenario.

2. Authorization Configuration

In order to validate access to your API it is necessary to evaluate a series of conditions: token is generated by AAC, token has not expired, token has appropriate scopes and claims. In case of JWT token, one can use the standard JWT libraries to validate the token content and signature based on the AAC JWKS keys (available from AAC metadata URL) and the contained claims (validity period, audience, subject, etc). In case of opaque token, it is possible to use AAC standard token introspection URL to obtain the same claims.

In order to be sure that the tokens used for the calls are correctly associated to your API, the recommended solution is to use custom services. Custom service logically represents your API as a resource server and allow for associating specific scopes and claims for these resources. To use custom service the requesting clients should ask for the corresponding scope and as a result (if granted) the tokens will include the custom service ID in the audience claim of the token. This is especially convenient when there are various clients calling your API and you need to validate their tokens.

See here for the details about configuring the custom services.

3. Token Validation

Validation of the token may rely on any standard OAuth2.0 bearer token validation or JWT validation library. The possible authorization extension may be implemented in order to validate custom claims provided by the token. In case of Java/Spring the following documentation may be used for reference implementation.