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.
Once your OAuth2 token asset is created, you can configure its settings on its associated asset screens.
This documentation describes the Details screen, which has unique fields for configuring the OAuth2 token asset.
When is an OAuth 2-legged token more appropriate?
If you need refresh tokens to be renewed automatically (without any user intervention) then you should choose REST resource OAuth 2-legged
The refresh token is obtained when authorisation is performed. If the token has an expiry, a new refresh token must be obtained by reauthorizing. OAuth 2 token requires user intervention to complete the authorisation. In other words, it cannot renew an expired refresh token without prompting the user for those credentials.
The OAuth2 2-legged token can perform this reauthorization process automatically using stored credentials.
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.
- 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.