Add OAuth2 to your APIs. Consumers must obtain an access token and add it in the Authorization header to authenticate and authorise their requests.

Add OAuth2 on top of an API by executing the following request:

curl -X POST -H "Content-Type: application/json" -d '{
"name": "oauth2",
"route_id": <route_id>,
"http_methods": [
  "*"
 ]
}' "http://localhost:9090/admin/plugin-configs"

JSON body parameters:

• route_id (required): the route this plugin configuration applies to.
• http_methods: the HTTP methods this plugin configuration applies to, e.g. POST. The asterisk character (*) captures all methods. Please keep all method names uppercase, e.g. use GET instead of get.

To call an API protected with OAuth2, consumers must use an access token. To be able to receive such a token, consumers must first register an OAuth2 client.

To register an OAuth2 client, use the following request:

curl -X POST -H "Content-Type: application/json" -d '{
	"scope": "<scopes>",
	"grant_types": ["client_credentials", "authorization_code"]
}' "http://localhost:9090/admin/consumers/<consumer_id>/oauth2-clients

URL parameters:

• <consumer_id>: The consumer ID. The OAuth2 client will be associated to this consumer.

JSON body parameters:

• scope: A space-separated string containing the OAuth2 scopes the client will be able to request. At the very least, it should include the API name, also known as route_id.
• grant_types: The OAuth2 flows the client can use. Possible values are according to the OAuth2 specification. Note that the password credentials grant is currently not supported by Hydra.

There are many more JSON body parameters, but they are presently not documented.

To obtain an access token, a consumer must use their OAuth2 client credentials according to the OAuth2 flows they support. The OAuth2 endpoints depend on the authorisation server's (e.g. Hydra) route configuration. By default, they are the following:

• auth endpoint: http://localhost:8080/hydra/realm1/oauth2/auth
• token endpoint: http://localhost:8080/hydra/realm1/oauth2/token

Example request for the client_credentials grant and a hypothetical API called balances:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic ZDcyYzZlYmItNjY1ZS00OWIyLTg4ZDktNTM4NGMwMTMwZGM4OlNCMnZxOi01WGE3dQ==" \
-d 'grant_type=client_credentials&scope=balances' \
"http://localhost:8080/hydra/realm1/oauth2/token"

Note that we are using scope=balances because we want to be able to call the balances API at the very least. The Authorization header string after the Basic keyword is the result of Base64 encoding of the string <Client ID>:<Client Secret>, according to the Basic Auth spec.

Example response:

{
    "access_token": "YIoXNgdA3aKkkyNz1Q69mQN7-ftVsOsstVbekdY1Oj4.dCtHcIfmvGlxtfuwxExvAfnspK8qzkr198fGXh2tPew",
    "expires_in": "3599",
    "scope": "balances",
    "token_type": "bearer"
}

To use an access token, a consumer must pass it to the request via the Authorization header.

curl -X GET -H "Authorization: Bearer <access_token>" "http://localhost:8080/<api>"

Example:

curl -X GET \
-H "Authorization: Bearer YIoXNgdA3aKkkyNz1Q69mQN7-ftVsOsstVbekdY1Oj4.dCtHcIfmvGlxtfuwxExvAfnspK8qzkr198fGXh2tPew" \
"http://localhost:8080/balances"

Acheron adds the following headers when proxying the request. These can be used by the API to take further decisions.

• ACHERON-OAUTH2-SUBJECT: The subject the access token is issued to.
• ACHERON-OAUTH2-CLIENT-ID: The client ID the access token is issued to.