OAuth 2 token
The OAuth2 token assets allow you to authenticate and store an OAuth 2.0 access token within Matrix, which can then be used in conjunction with other assets, such as the OAuth account manager, for OAuth integration within the system.
When the OAuth2 token asset is accessed from the frontend, the system will redirect the user for OAuth 2.0 authentication. Once the user is successfully authenticated, the resulting access token will be stored within this asset.
When the asset is reaccessed, and this token is still valid, the stored token will be reused. If the token has expired, a new access token will be retrieved by re-authenticating or using an available refresh token.
The OAuth2 2-legged token asset works similarly, except the authentication is all done on the server-side and does not require the user to redirect and authenticate on the frontend.
Once your OAuth2 token asset is created, you can configure its settings on its associated asset screens.
This documentation will describe the Details screen, which is different for an OAuth2 token asset.
Details screen
OAuth 2.0 settings
The OAuth 2.0 settings section of the Details screen allows you to specify the details on the OAuth service provider and configure where users will be redirected after the authorization process is complete.
The OAuth 2.0 settings section is shown in the figure.
The fields available are as follows:
- Client ID
-
Enter the client identifier provided to you by the authorization service provider. This field is compulsory.
- Client secret
-
Enter the client secret provided to you by the authorization service provider.
- Authorization endpoint
-
Enter the authorization endpoint URL for the authorization service provider.
- Token endpoint
-
Enter the token endpoint URL for the authorization service provider.
- Scope
-
Enter your authentication scope string. This will determine the user information that can be accessed from the authorization service provider.
- Redirect URI
-
Enter the URI to redirect to after authorization. If this field is left blank, the current frontend URI will be used.
The URI must be allowed on the authorization service provider. The OAuth2 2-legged token asset does not require the Authorization endpoint and Redirect URI field and is therefore unavailable on that asset’s Details screen.
Advanced settings
The Advanced settings section of the Details screen allows you to specify the token and authorization types of the access token and define its parameter name. The Advanced settings section is shown in the figure.
The following options must be configured before the access token has been created and stored.
The fields available are as follows:
- Access token URI parameter name
-
Specify the parameter name for the access token, as indicated by the authorization service provider. If you are unsure of the parameter name, use the default value of
access_token. - Authorization type
-
Select the authorization type for the access token, as indicated by the authorization service provider. The authorization types available are URI, authorization basic, and form. If you are unsure of the authorization type, use the default selection of URI.
- Access token type
-
Select the access token type, as indicated by the authorization service provider. The token types available are URI, Bearer, and OAuth. If you are unsure of the authorization type, use the default; URI.
Access token
The Access token section of the Details screen allows you to modify the way tokens are stored on the OAuth2 token asset and display the details of any access token that is currently being stored. The Access token section is shown in the figure.
The following options must be configured before the access token has been created and stored.
In the Token storage field, specify how the token should be stored. The following options are available:
- Session
-
Store the access token in the session of the current user. This means that once the user logs out or the browser is closed, the token will be lost. By default, the access token will be stored using this option.
- Global permanent
-
Store the access token globally for all users as a permanent attribute.
This storage option will require the user to have write access to be able to refresh and store the access token. - Per-user permanent
-
Store the access token for the individual user permanently in the database. The details of the OAuth2 token will be displayed in the Access token field, including the token string, the date of expiry, and whether a refresh token is available.