Help Center

Menu

OAuth account manager

Overview

The OAuth account manager allows you to integrate OAuth2 authentication within Matrix. This will allow users to sign in as a local system user using, for example, their Facebook or Google account.

When a user visits the OAuth account manager asset, the system will redirect the user for OAuth 2.0 authentication. After successfully authenticating their account, the user will be logged into the system using their linked local user account if one has already been created.

If no account has been linked for the current user, Matrix will either identify an associated account within Matrix to link to (that is, one the user is also logged in with) or create a new local user account within the system to link.

After the OAuth user has been successfully authenticated and linked, their user profile data will be retrieved through the service provider’s profile API. This data is stored within the session and is available using the following keyword replacements:

%globals_session_OAuth_profile%

The entire profile data as a JSON array.

%globals_session_OAuth_profile_xx_yy%

Specified data from the profile JSON array, using the structure xx.yy.

Once your OAuth account manager asset is created, you can configure its settings on its associated asset screens.

The majority of the screens available on the OAuth account manager are similar to those of both a standard page and an Asset builder page.

Read the Asset screens and Asset builder page documentation for more information.

This documentation will describe the Details and Linked accounts screens, which are different for an OAuth account manager asset.

Additional dependant assets

OAuth account manager dependant assets

When you create an OAuth account manager within your system, several assets are automatically created beneath it. You can use these assets to define the contents and layout of the OAuth account manager.

Create user

This bodycopy is used to define the layout to display to an OAuth user when no associated user account is found within Matrix. This will allow the user to create and link to a new user account within the system.

Create link

This bodycopy is used to define the layout to display to an OAuth user when an associated user account is found within Matrix. This will allow the user to link these user accounts, enabling access to the system.

Logged in

This bodycopy is used to define the layout to display to a logged-in OAuth user with a linked Matrix account.

Login failed

This bodycopy is used to define the layout to display to a user when sign-in fails on the OAuth account manager.

Details screen

General settings

The General settings section of the Details screen lets you select the OAuth2 token asset to use on the OAuth account manager, and configure its general settings.

The general settings section of the *Details* screen

The fields available are as follows:

OAuth 2.0 token

Specify the OAuth2 token asset to use for OAuth authorization on the OAuth account manager. Read the OAuth 2 token documentation for more information.

User profile API

Specify the API location to retrieve the user profile information from (in JSON format).

The specified API should return the user’s ID as a minimum.
User ID location

Specify the user ID location in the user profile API response specified above. To specify a multi-level location, use the result.user.ID format. Leaving this field empty will use the default location of ID to source the user ID.

User creation settings

The User creation settings section of the Details screen lets you configure the user asset types that will be created during the OAuth authentication process when no linked Matrix user is found. In the Asset creation section is shown in the figure below.

The user creation settings section of the *Details* screen

The fields available are as follows:

Matrix user to create

Select the user account types to create for new Matrix users during the OAuth authentication process. The account types available are:

  • User

  • Backend user

  • Simple edit user

  • System administrator

Read the Manage users and permissions documentation for more information.

Metadata schemas to apply

This field allows you to select a metadata schema that will automatically be applied to the created user assets. Users can input the metadata of the nominated schema when creating their accounts.

Allow linking to existing users

This option allows you to link an existing Matrix user accounts with their authenticated OAuth identities. This means that if a user is logged into the system and their account is OAuth authenticated, the OAuth account manager will prompt the user to link their accounts if they have not already been. By default, this option is enabled.

Automatic creation

This option allows for the automatic creation of linked local users when a user is not logged into Matrix. By default, this option is a manual process, with users being allowed to create a new user account during OAuth authentication. Enabling this field will automate this creation, skipping this procedure.

Populate user attributes

The Populate user attributes section of the Details screen lets you define the user attributes of your OAuth authorized users using the profile data returned from the API.

The populate user attributes section of the Details screen

The following user attributes can be set:

  • First name

  • Last name

  • Login date

  • Login IP

  • Disallow password sign in

  • Email

  • Restrictions

  • History passwords

  • Username

  • Password

  • Locale

To set an attribute:

  1. Select the attribute in the New attribute to set? field.

  2. Select Save; the attribute field will be displayed in the Populate user attributes section.

  3. In the Location field of the attribute, enter the source string to retrieve the specified attribute data from. For example, when integrating Google authentication, the first name user attribute can be sourced from the given_name attribute data of the Google API.

To delete a set attribute:

  1. Select the corresponding Delete check-box.

  2. Select Save. In the attribute will be removed from the Populate user attributes section.

A list of standard user attribute strings can be found in the OAuth Provider Settings appendix in this documentation.

Sync user attributes

The Sync user attributes section of the Details screen lets you configure a set of user attributes of your OAuth authorized users, populated from the profile data returned from the API, that will sync each time a user logs into the system.

The following user attributes can be set:

  • First name

  • Last name

  • Login date

  • Login IP

  • Disallow password sign-in

  • Email

  • Restrictions

  • History passwords

  • Username

  • Password

  • Locale

To set an attribute:

  1. Select the attribute in the Add attribute field.

  2. Select Save; the Attributes to sync on sign-in field will be displayed in the sync user attributes section.

  3. In the Value field of the attribute, enter the source string from which to retrieve the specified attribute data.

To delete a set attribute:

  1. Select the corresponding Delete check-box.

  2. Select Save. The attribute will be removed from the Sync user attributes section.

Return location

The Return location section of the Details screen lets you set the location for users to redirect to after the OAuth authentication process.

The fields available in this section are as follows:

URL

Enter the URL of the web page to return users to, for example, http://www.example.com. This option is useful when wanting to return users to a page outside of your Matrix system.

This URL requires the web protocol to be included (for example, \http://).

Or

Asset

Select the asset within the system to which users are returned.

Or

Query string parameter

Specify the name of a query string parameter whose value will specify the URL to return users to, for example, if this value is URL and the inbound query string includes ?URL=http://example.com, users will be returned to http://example.com.

Letting the return location URL be dynamic using a query string can result in attackers using this to redirect users to malicious sites. Use custom redirect implementation on the "logged in bodycopy" instead to control what domains can be used for the dynamic redirect URL.
Redirect after sign-in

If enabled, the user will get redirected to the specified location as soon as they sign in.

Redirect after user created

If enabled, the user will get redirected to the specified location as soon as their linked Matrix user account has been created.

This setting will not work when Redirect after sign-in is enabled.
Redirect after link created

If enabled, the user will get redirected as soon as their existing Matrix user account is linked with their external signed-in account.

Linked accounts screen

The Linked accounts screen lists the Matrix user accounts that have been linked to an OAuth identity on the OAuth account manager. The Linked accounts screen is shown in the figure.

The linked accounts screen on the OAuth account manager

The information displayed on this screen includes:

  • The Matrix user account that has been linked.

  • The OAuth user identification number.

  • The date the link was created.