User Assertion Workflow

In this workflow the user provides the user assertion to obtain an access token from the OAuth token service.

The user assertion grant describes a flow where the client application, together with its client identifier and password, sends the user assertion in exchange for an access token. This flow has different security properties than the other OAuth flows. The primary difference is that the user’s credentials are never accessible to the application.

Key Characteristics of the User Assertion Workflow

The user assertion workflow:

• It’s used with confidential clients.

• It uses the assertion of the Resource Owner.

• It isn’t redirection-based; it takes a request only from the client application to the authorization server, and the user is not redirected between interfaces to authorize the request.

Workflow of the User Assertion Grant

1. Obtain user assertion: The user provides the assertion. The client application can use an already-generated user assertion or build a new assertion. The user assertion is a standard JSON web token (JWT), to be signed by a trusted client using its private key. Verify that the following claims are part of the user assertion:

   Header

   {
   "alg": "RS256", 
   "typ": "JWT", 
   "x5t": "<X5t of the certificate>"
   }

   Body

   { 
   "exp": <Expiry Time in seconds>, 
   "sub": "<username like [e-mail]>", 
   "aud": [   "oauth.idm.oracle.com" ], 
   "iss": "<clientid>", 
   "oracle.oauth.sub.id_type": "LDAP_UID", 
   "prn": "<username like [e-mail]>", 
   "jti": "<Globally Unique Id representing the token>", 
   "iat": <Issued at Time in seconds>, 
   "user.tenant.name": "<tenantname>", 
   "oracle.oauth.prn.id_type": "LDAP_UID"
   }

2. Request an access token: The user assertion is exchanged for an access token. The client application makes a request to the authorization server, including the user’s assertion and either the client’s credentials or the client assertion. The client application can use an already generated client assertion or build a new assertion.

   Note:

   In the regular flow the access token's expiry claim is obtained from the configuration and the expiry time of the access token is by default 1 hour. However, in case of using the self-signed user assertion and client credentials flow, the expiry time of the access token can be modified to a value up to 90 days. The OAuth Server looks for the exp claim in the user assertion to determine the expiry claim of the resulting access token.

   Obtain an access token by using different scenarios in the user assertion workflow:

   • Obtaining an Access Token by Using a Self-Signed User Assertion and the Client Credentials

   • Obtaining an Access Token by Using a Self-Signed User Assertion and a Client Assertion

3. Receive an access token from the authorization server: The authorization server authenticates the client based on the client identifier and secret, determines whether it is authorized for making this request, and verifies the user’s assertion and other parameters that are supplied. If everything is verified successfully, then the authorization server returns an access token in response. This is described in Successful Authorization.

   If the authorization request fails for any reason, then the authorization server returns a response containing information about the error. This is described in Authorization Error.

4. Use the access token to make a service request: The OAuth client makes a REST API call to the resource server using the access token to access the protected resource.

5. Send a response: The OAuth resource server sends a response to the client application that made the request.

6. Grant access to the resource: The enduser or service gets access to the protected resource.