Oracle® Fusion Middleware
API Gateway OAuth 2.0 Authentication Flows

The API Gateway can use the OAuth 2.0 protocol for authentication and authorization. The API Gateway can act as an OAuth 2.0 Authorization Server and supports several OAuth 2.0 flows that cover common Web server, JavaScript, device, installed application, and server-to-server scenarios. This topic describes each of the supported OAuth 2.0 flows in detail, and shows how to run example client applications.

The Authorization Code or Web server flow is suitable for clients that can interact with the end-user’s user-agent (typically a Web browser), and that can receive incoming requests from the authorization server (can act as an HTTP server). The Authorization Code flow is also known as the Three-Legged OAuth flow.

The Authorization Code flow is as follows:

Obtaining an access token

The detailed steps for obtaining an access token are as follows:

1. Redirect the user to the authorization endpoint with the following parameters:

The following is an example URL:

https://apigateway/oauth/authorize?client_id=SampleConfidentialApp&
response_type=code&&redirect_uri=http%3A%2F%2Flocalhost%3A8090%2Fauth%2Fredirect.html&
scope=https%3A%2F%2Flocalhost%3A8090%2Fauth%2Fuserinfo.email

2. The response to the above request is sent to the redirect_uri. If the user approves the access request, the response contains an authorization code and the state parameter (if included in the request). If the user does not approve the request, the response contains an error message. All responses are returned to the Web server on the query string. For example:

https://localhost/oauth_callback&code=9srN6sqmjrvG5bWvNB42PCGju0TFVV

3. After the Web server receives the authorization code, it may exchange the authorization code for an access token and a refresh token. This request is an HTTPS POST, and includes the following parameters:

* If the client_id and client_secret are not provided as parameters in the HTTP POST, they must be provided in the HTTP Basic Authentication header (Authorization base64Encoded(client_id:client_secret)).

The following example HTTPS POST shows some parameters:

POST /api/oauth/token HTTP/1.1 
Content-Type: application/x-www-form-urlencoded 

client_id=SampleConfidentialApp&client_secret=6808d4b6-ef09-4b0d-8f28-3b05da9c48ec
 &code=9srN6sqmjrvG5bWvNB42PCGju0TFVV&redirect_uri=http%3A%2F%2Flocalhost%3A809
 0%2Fauth%2Fredirect.html&grant_type=authorization_code&format=query

4. After the request is verified, the API Gateway sends a response to the client. The following parameters are in the response body:

The following is an example response:

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
Pragma: no-cache{
    "access_token": “O91G451HZ0V83opz6udiSEjchPynd2Ss9......",
    "token_type": "Bearer",
    "expires_in": "3600",
}

5. After the Web server has obtained an access token, it can gain access to protected resources on the Resource Server by placing it in an Authorization: Bearer HTTP header:

GET /oauth/protected HTTP/1.1
Authorization: Bearer O91G451HZ0V83opz6udiSEjchPynd2Ss9
Host: apigateway.com

For example, the curl command to call a protected resource with an access token is as follows:

curl -H "Authorization: Bearer O91G451HZ0V83opz6udiSEjchPynd2Ss9" 
  https://apigateway.com/oauth/protected

Running the sample client

The following Jython sample client creates and sends an authorization request for the authorization grant flow to the Authorization Server:

INSTALL_DIR/samples/scripts/oauth/authorization_code.py

To run the sample, perform the following steps:

Further information

For details on API Gateway filters that support this flow, see the following topics:

The Implicit Grant (User-Agent) authentication flow is used by client applications (consumers) residing in the user's device. This could be implemented in a browser using a scripting language such as JavaScript, or from a mobile device or a desktop application. These consumers cannot keep the client secret confidential (application password or private key).

The User Agent flow is as follows:

Obtaining an access token

The detailed steps for obtaining an access token are as follows:

1. Redirect the user to the authorization endpoint with the following parameters:

The following is an example URL:

https://apigateway/oauth/authorize?client_id=SampleConfidentialApp&response_type=
  token&&redirect_uri=http%3A%2F%2Flocalhost%3A8090%2Fauth%2Fredirect.html&scope=
  https%3A%2F%2Flocalhost%3A8090%2Fauth%2Fuserinfo.email

2. The response to the above request is sent to the redirect_uri. If the user approves the access request, the response contains an access token and the state parameter (if included in the request). For example:

https://localhost/oauth_callback#access_token=19437jhj2781FQd44AzqT3Zg
 &token_type=Bearer&expires_in=3600

If the user does not approve the request, the response contains an error message.

3. After the request is verified, the API Gateway sends a response to the client. The following parameters are contained in the fragment of the redirect:

4. After the application has obtained an access token, it can gain access to protected resources on the Resource Server by placing it in an Authorization: Bearer HTTP header:

GET /oauth/protected HTTP/1.1
Authorization: Bearer O91G451HZ0V83opz6udiSEjchPynd2Ss9
Host: apigateway.com

For example, the curl command to call a protected resource with an access token is as follows:

curl -H "Authorization: Bearer O91G451HZ0V83opz6udiSEjchPynd2Ss9" 
https://apigateway.com/oauth/protected

Running the sample client

The following Jython sample client creates and sends an authorization request for the implicit grant flow to the Authorization Server:

INSTALL_DIR/samples/scripts/oauth/implicit_grant.py

To run the sample, perform the following steps:

Further information

For details on the API Gateway filter that supports this flow, see the Authorization Code Flow filter.

The Resource Owner password credentials flow is also known as the username-password authentication flow. This flow can be used as a replacement for an existing login when the consumer already has the user’s credentials.

The Resource Owner password credentials grant type is suitable in cases where the Resource Owner has a trust relationship with the client (for example, the device operating system or a highly privileged application). The Authorization Server should take special care when enabling this grant type, and only allow it when other flows are not viable.

This grant type is suitable for clients capable of obtaining the Resource Owner's credentials (username and password, typically using an interactive form). It is also used to migrate existing clients using direct authentication schemes such as HTTP Basic or Digest authentication to OAuth by converting the stored credentials to an access token.

Requesting an access token

The client token request should be sent in an HTTP POST to the token endpoint with the following parameters:

The following is an example HTTP POST request:

POST /api/oauth/token HTTP/1.1
Content-Length: 424
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Host: 192.168.0.48:8080
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JWgrant_type=password&username=
 johndoe&password=A3ddj3w

Handling the response

The API Gateway will validate the resource owner’s credentials and authenticate the client against the Oracle Client Application Registry. An access token, and optional refresh token, is sent back to the client on success. For example, a valid response is as follows:

HTTP/1.1 200 OK
 Cache-Control: no-store
 Content-Type: application/json
 Pragma: no-cache
 {
     "access_token": “O91G451HZ0V83opz6udiSEjchPynd2Ss9......",
     "token_type": "Bearer",
     "expires_in": "3600",
     “refresh_token”: “8722gffy2229220002iuueee7GP...........”
 }

Running the sample client

The following Jython sample client sends a request to the Authorization Server using the Resource Owner password credentials flow:

INSTALL_DIR/samples/scripts/oauth/resourceowner_password_credentials.py

To run the sample, open a shell prompt at INSTALL_DIR/samples/scripts, and execute the following command:

> run oauth/resourceowner_password_credentials.py

The script outputs the following:

Sending up access token request using grant_type set to password
Response from access token request: 200
Parsing the json response
**********************ACCESS TOKEN RESPONSE***********************************
Access token received from authorization server lrGHhFhFwSmycXStIza1jjvXlSaac9
 JNIgviF7oPiV8OnxlSIsrxVA
Access token type received from authorization server Bearer
Access token expiry time: 3600
******************************************************************************
Now we can try access the protected resource using the access token
Executing get request on the protected url
Response from protected resource request is: 200
<html>Congrats! You've hit an OAuth protected resource</html>

Further information

For details on the API Gateway filter that supports this flow, see Resource Owner Credentials.

The client credentials grant type must only be used by confidential clients. The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control. The client can also request access to those of another Resource Owner that has been previously arranged with the Authorization Server (the method of which is beyond the scope of the specification).

Requesting an access token

The client token request should be sent in an HTTP POST to the token endpoint with the following parameters:

The following is an example POST request:

POST /api/oauth/token HTTP/1.1
Content-Length: 424
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Host: 192.168.0.48:8080
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
grant_type=client_credentials

Handling the response

The API Gateway authenticates the client against the Oracle Client Application Registry. An access token is sent back to the client on success. A refresh token is not included in this flow. An example valid response is as follows:

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
Pragma: no-cache
{    "access_token": “O91G451HZ0V83opz6udiSEjchPynd2Ss9......",
     "token_type": "Bearer",
     "expires_in": "3600"
}

Running the sample client

The following Jython sample client sends a request to the Authorization Server using the client credentials flow:

INSTALL_DIR/samples/scripts/oauth/client_credentials.py

To run the sample, open a shell prompt at INSTALL_DIR/samples/scripts, and execute the following command:

> run oauth/client_credentials.py

The outputs the following:

Sending up access token request using grant_type set to client_credentials
Response from access token request: 200
Parsing the json response
**********************ACCESS TOKEN RESPONSE***********************************
Access token received from authorization server 
OjtVvNusLg2ujy3a6IXHhavqdEPtK7qSmIj9fLl8qywPyX8bKEsjqF
Access token type received from authorization server Bearer
Access token expiry time: 3599
******************************************************************************
Now we can try access the protected resource using the access token
Response from protected resource request is: 200
<html>Congrats! You've hit an OAuth protected resource</html>

Further information

For details on the API Gateway filter that supports this flow, see Access Token Using Client Credentials.

A JSON Web Token (JWT) is a JSON-based security token encoding that enables identity and security information to be shared across security domains.

In the OAuth 2.0 JWT flow, the client application is assumed to be a confidential client that can store the client application’s private key. The X.509 certificate that matches the client’s private key must be registered in the Oracle Client Application Registry. The API Gateway uses this certificate to verify the signature of the JWT claim. For information on creating a private key and certificate, see the section called “Generating a Certificate and Private Key for a Client Application”.

For more details on the OAuth 2.0 JWT flow, see

http://self-issued.info/docs/draft-ietf-oauth-jwt-bearer-00.html

Creating a JWT bearer token

To create a JWT bearer token, perform the following steps:

Requesting an access token

The JWT bearer token should be sent in an HTTP POST to the Token Endpoint with the following parameters:

The following is an example POST request:

POST /api/oauth/token HTTP/1.1
Content-Length: 424
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Host: 192.168.0.48:8080
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJS
 UzI1NiJ9.eyJpc3MiOiAiU2FtcGxlQ29uZmlkZW50aWFsQXBwIiwgImF1ZCI6ICJodHRwOi8vYXBpc2Vy
 dmVyL2FwaS9vYXV0aC90b2tlbiIsICJleHAiOiAiMTM0MTM1NDYwNSIsICJpYXQiOiAiMTM0MTM1NDMwN
 SJ9.ilWR8O8OlbQtT5zBaGIQjveOZFIWGTkdVC6LofJ8dN0akvvD0m7IvUZtPp4dx3KdEDj4YcsyCEAPh
 fopUlZO3LE-iNPlbxB5dsmizbFIc2oGZr7Zo4IlDf92OJHq9DGqwQosJ-s9GcIRQk-IUPF4lVy1Q7PidP
 WKR9ohm3c2gt8

Handling the response

The API Gateway returns an access token if the JWT claim and access token request are properly formed, and the JWT has been signed by the private key matching the registered certificate for the client application in the Oracle Client Application Registry.

For example, a valid response is as follows:

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
Pragma: no-cache
{
    "access_token": “O91G451HZ0V83opz6udiSEjchPynd2Ss9......",
    "token_type": "Bearer",
    "expires_in": "3600",
}

Running the sample client

The following Jython sample creates and sends a JWT Bearer token to the Authorization Server:

INSTALL_DIR/samples/scripts/oauth/jwt.py

To run the sample, open a shell prompt at INSTALL_DIR/samples/scripts, and execute the following command:

> run oauth/jwt.py

Further information

For details on the API Gateway filter that supports this flow, see Access Token Using JWT.

In some cases a user may wish to revoke access given to an application. An access token can be revoked by calling the API Gateway revoke service and providing the access token to be revoked. A revoke token request causes the removal of the client permissions associated with the particular token to access the end-user's protected resources.

The endpoint for revoke token requests is as follows:

https://<API Gateway>:8089/api/oauth/revoke

The token to be revoked should be sent to the revoke token endpoint in an HTTP POST with the following parameter:

The following is an example POST request:

POST /api/oauth/revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Host: 192.168.0.48:8080
Authorization: Basic U2FtcGxlQ29uZmlkZW50aWFsQXBwOjY4MDhkNGI2LWVmMDktNGIwZC04ZjI4LT
NiMDVkYTljNDhlYw==token=4eclEUX1N6oVIOoZBbaDTI977SV3T9KqJ3ayOvs4gqhGA4

Running the sample client

The following Jython sample client creates a token revoke request to the Authorization Server:

INSTALL_DIR/samples/scripts/oauth/revoke_token.py

To run the sample, open a shell prompt at INSTALL_DIR/samples/scripts, and execute the following command:

> run oauth/revoke_token.py

When the Authorization Server receives the token revocation request, it first validates the client credentials and verifies whether the client is authorized to revoke the particular token based on the client identity.

The Authorization Server decides whether the token is an access token or a refresh token:

Response codes

The following HTTP status response codes are returned:

The following is an example response:

Token to be revoked: 3eXnUZzkODNGb9D94Qk5XhiV4W4gu9muZ56VAYoZiot4WNhIZ72D3
Revoking token...............
Response from revoke token request is: 200
Successfully revoked token

Further information

For details on the API Gateway filter that supports this flow, see Revoke a Token.

You can use the Token Info Service to validate that an access token issued by the API Gateway. A request to the tokenInfo service is an HTTP GET request for information in a specified OAuth 2.0 access token.

The endpoint for the token information service is as follows:

https://<apigateway>:8089/api/oauth/tokeninfo

Getting information about a token from the Authorization Server only requires a GET request to the tokeninfo endpoint. For example:

GET /api/oauth/tokeninfo HTTP/1.1
Host: 192.168.0.48:8080
access_token=4eclEUX1N6oVIOoZBbaDTI977SV3T9KqJ3ayOvs4gqhGA4

This request includes the following parameter:

The following example uses this parameter:

https://apigateway/api/oauth/tokeninfo?access_token=4eclEUX1N6oVIOoZBba
 DTI977SV3T9KqJ3ayOvs4gqhGA4

Running the sample client

The following Jython sample client creates a token revoke request to the Authorization Server:

INSTALL_DIR/samples/scripts/oauth/token_info.py

To run the sample, open a shell prompt at INSTALL_DIR/samples/scripts, and execute the following command:

> run oauth/token_info.py

This displays the following dialog:

When the Authorization Server receives the Token Info request, it first ensures the token is in its cache (EhCache or Database), and ensures the token is valid and has not expired.

The following is an example response:

Get token info for this token: BcYGjPOQSCrtbEc1F0ag8zf6OT9rCaMLiI1dYjFLT5zhxz3x5ScrdN
Response from token info request is: 200
**********************TOKEN INFO RESPONSE***********************************
Token audience received from authorization server: SampleConfidentialApp
Scopes user consented to: https://localhost:8090/auth/userinfo.email
Token expiry time: 3566
User id : admin
******************************************************************************

Response codes

The following HTTP Status codes are returned:

The response is sent back as a JSON message. For example:

{
 "audience" : "SampleConfidentialApp",
   "user_id" : "admin",
   "scope" : "https://localhost:8090/auth/userinfo.email",
   "expires_in" : 2518
 }

You can get additional information about the access token using message attributes. For more details, see the section called “Querying OAuth 2.0 Message Attributes”.

Further information

For details on the API Gateway filter that supports this flow, see OAuth Access Token Information.