The OAuth2 plugin can run in one of two flows: client credentials or authorization code.
The client credentials flow works out of the box, without building any authorization page.
The clients need to use the /oauth2/token endpoint to request an access token. For more details, see Enable OAuth 2.0 authentication with Kong Gateway.
The authorization code flow requires a few extra setup steps.
After provisioning Consumers and associating OAuth 2.0 credentials to them, you must also:
- Implement an authorization page on your web application.
- Provide internal documentation on how to consume your OAuth 2.0 protected services, so that developers accessing your Service know how to build their client implementations.
Building the authorization page is the primary task that the plugin itself can’t do out of the box, because it requires checking that the user is properly logged in, and this operation is strongly tied with your authentication implementation.
The authorization page is made up of two parts:
- The frontend page that the user sees, and that allows them to authorize the client application to access their data.
- The backend that processes the HTML form displayed in the frontend. This backend connects with the OAuth 2.0 plugin in Kong Gateway and redirects the user to a third party URL.
You can see a sample implementation in node.js + express.js on GitHub.
Here’s how it works:
-
The client application redirects the end user to the authorization page on your web application, passing client_id, response_type, and scope (if required) as query string parameters.
-
The web application ensures that the user is logged in, then shows the authorization page.
- The client application sends the
client_id in the query string, from which the web application can retrieve both the OAuth 2.0 application name and developer name, by making the following request to Kong Gateway:
curl localhost:8001/oauth2?client_id=$CLIENT_ID
-
If the end user authorizes the application, the form submits the data to your backend with a POST request, sending the client_id, response_type, and scope parameters that were placed in <input type="hidden" .. /> fields.
- The backend makes a
POST request to Kong Gateway at your Service address, on the /oauth2/authorize endpoint, with the provision_key, authenticated_userid, client_id, response_type, and scope parameters. If an Authorization header was sent by the client, that must be added too. For example:
curl https://$SERVICE.com/oauth2/authorize \
--header "Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW" \
--data "client_id=$CLIENT_ID" \
--data "response_type=$RESPONSE_TYPE" \
--data "scope=$SCOPE" \
--data "provision_key=$PROVISION_KEY" \
--data "authenticated_userid=$USER_ID"
The provision_key is the key the plugin generates when it’s added to the Service. authenticated_userid is the ID of the logged-in end user who grants the permission.
-
Kong Gateway responds with a JSON response:
{
"redirect_uri": "http://some/url"
}
The response can be either a 200 OK or 400 Bad Request.
-
In both cases, Kong Gateway ignores the response status code and redirects the user to whatever URI is being returned in the redirect_uri property.
-
The client application takes it from here, and continues the flow with Kong Gateway with no other interaction with your web application. For example, if it’s an Authorization Code Grant flow, the client app might exchange the authorization code for an access token.
-
After retrieving the access token,, the client application makes requests on behalf of the user to your upstream service.
- Access tokens can expire, and when that happens the client application needs to renew the access token with Kong Gateway and retrieve a new one.
In this flow, the steps that you need to implement are:
- The login page (step 2)
- The Authorization page, with its backend that simply collects the values, makes a
POST request to Kong Gateway, and redirects the user to whatever URL Kong Gateway has returned (steps 3 to 7)
