Writing OAuth2 clients

This documentation is intended for users or administrators who wish to write OAuth2 clients to connect to the platform. This page provides a description of OAuth2 and details about the implementation of OAuth2.

OAuth2 overview

The OAuth2 authorization framework enables third-party applications to obtain controlled access to a service. OAuth2 improves on the traditional client-server authorization model by providing a layer that enables clients (like a third-party application) to request access through the use of a specifically-issued access tokens and refresh tokens, rather than a user’s credentials or static bearer tokens. OAuth2 manages this access through the use of grants, which are methods of obtaining access tokens.

Supporting OAuth2 integration

The following sections describe how to support OAuth2 in a third-party application. Throughout the document, client refers to the third-party application, authorization server refers to Gotham’s authorization server, and user refers to the end-user of the third-party application.

To use OAuth2 with Gotham, you must register your application by following the Registering Third-Party Applications instructions and choose one of the authorization options in the next sub-sections.

Authorization code grant

The authorization code grant allows the client to act on behalf of existing Gotham users. The application must request the set of platform permissions they need access to, then a Gotham user must explicitly grant the client access to those permissions on their account. Gotham allows the client to be restricted to a limited set of resources, or to all the resources a user can access.

The authorization code grant works as follows:

1. The client creates a code_verifier and code_challenge. This is recommended but not required for confidential clients, such as server-based applications, that can safely store a client secret. It is required for public clients, such as native apps, that cannot safely store a client secret.
   • The code_verifier is a cryptographically random string that contains A-Z, a-z, 0-9, - (hyphen), . (period), _ (underscore), and ~ (tilde), and is 43 to 128 characters long.
   • The code_challenge is derived by performing the SHA256 of the code_verifier and then converting that to a Base64-URL-encoded value without padding.
2. The client application should open a browser and send the user to the authorization endpoint URL with the following parameters added as query parameters:
   • response_type: This should be set to code.
   • client_id: This should be set to the ID generated when the third-party application was registered in Gotham.
   • redirect_uri: This tells the authorization server where to redirect the user after the user approves the request. If not specified, it will default to the redirect URI value in the Third-Party application setting in Gotham.
   • scope: This defines the permissions requested. Scopes for public APIs are in the API documentation. Add the offline_access scope to get a refresh token. If you want multiple scopes, concatenate the scopes using a space as a delimiter.
   • state: This is a random string generated by the application that will be passed back to the application as is. The application should check that the value returned matches the original string to prevent CSRF attacks.
   • code_challenge: If the client created a code_challenge, it should populate this parameter. The authorization server will internally associate the code_challenge parameter with the authorization code it generates.
   • code_challenge_method: This should be set to S256.
3. When the user visits the URL, the authorization server presents the user with a prompt similar to the following and the user then can choose to approves the app’s request.

1. If the request is successful, the authorization server then redirects the user to the redirect URI that was specified along with the following parameters added as query parameters:
   • code: This is the authorization code that the authorization server generates.
   • state: This is the same parameter the client passed in the authorization request. The client should check that it matches the original state parameter that was sent in the request.
2. The client should then exchange the authorization code for an access token by calling the token endpoint. The following parameters should be sent using the application/x-www-form-urlencoded format in the request body.
   • grant_type: This should be set to authorization_code.
   • code: The code that was received from the authorization server.
   • client_id: This should be set to the ID generated when the third-party application was registered in Gotham.
   • code_verifier: If the client generated a code_verifier, it should send it in this request. The authorization server will verify that the code_verifier matches the code_challenge that was sent in the previous request.
3. The authorization server then responds with an access token which can then be used by the client to access the requested resources such as REST APIs. The response contains the following parameters:
   • access_token: The token that can be used by the client to access the requested resources.
   • token_type: The type of the token that was issued.
   • expires_in: The lifetime in seconds of the access token.
   • refresh_token: This is returned only if the requested scope included offline_access. This should be used if the client wants to refresh the access token without the user being present to authorize the request. For more information, see Refreshing an access token.

Client credentials grant

The client credentials grant is designed for non-interactive service-user style workflows where actions the client makes are not associated to normal platform users. The client does not act on behalf of normal platform users.

Instead, this grant type automatically creates a service user associated with the client that can then be granted permissions to access platform resources. The token obtained by this grant can be used to access resources on behalf of the created service user. The username of the service user account is the same as the client ID of the application.

The client credentials grant works as follows:

1. The client calls the token endpoint. The following parameters should be sent using the application/x-www-form-urlencoded format in the request body:
   • grant_type: This should be set to client_credentials.
   • client_id: This should be set to the ID generated when the third-party application was registered in Gotham.
   • client_secret: This should be set to the client secret that was generated when the third-party application was registered in Gotham.
2. The authorization server then responds back with the following:
   • access_token: The token that can be used by the client to access the requested resources.
   • token_type: The type of the token that was issued.
   • expires_in: The lifetime in seconds of the access token.
3. The client can then use the access token to access the requested resources.

Refreshing an access token

Access tokens expire after some time and will need to be obtained again. Any client that needs access to the Gotham API when the user is not present will need to refresh the token.

This can be done by following these steps:

1. The client should follow the steps outlined in Authorization Code Grant and specify offline_access as part of the requested scope parameter.
2. The client should save the returned refresh_token that was returned in the final step of Authorization Code Grant.
3. If the access token expires, the client can then refresh the token by calling the token endpoint endpoint using the following parameters:
   • grant_type: This should be set to refresh_token.
   • refresh_token: The refresh token that was obtained previously for the given user.
   • client_id: This should be set to the ID generated when the third-party application was registered in Gotham.
   • client_secret: This should be set to the client secret that was generated when the third-party application was registered in Gotham.
4. The authorization server will then respond with the following:
   • access_token The token that can be used by the client to access the requested resources.
   • token_type: The type of the token that was issued.
   • expires_in: The lifetime in seconds of the access token.
   • refresh_token: The refresh token that can be used next time to refresh the access token again. Note that platform rotates refresh_token every time a refresh_token grant is called. Make sure you save both the access_token and the refresh_token.

OAuth2 API reference

The following endpoints can be used to obtain OAuth2 tokens.

Authorization endpoint

GET /multipass/api/oauth2/authorize

The authorization endpoint, used by the client to obtain an authorization code.

Query parameters

Redirect query parameters

If the request is successful, the user’s browser is redirected to the redirect URI specified in the Third-Party application settings or in the redirect URI passed in the request. The following query parameters will be present in the redirect request URI:

Token endpoint

POST /multipass/api/oauth2/token

The token endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token.

Header parameters

Request body parameters

Response body

The response JSON has the following fields.

Endpoint errors

Error response body

If the request fails, the user’s browser will only be redirected if the access request is denied. In all other cases, an HTML error page is returned which includes the fields below.

Error codes