OAuth2

Administration PageApplication/ContractSyracuse/Collaborationclassoauth2sRepresentationoauth2

When starting the application, users are granted access, or not, depending on their identity. In many cases (database or LDAP authentication), the application handles the authentication process on its own. However, it is also possible to go through an authentication server first: users have to successfully connect to the authentication server for the application to grant them access.

Principles of OAuth2 authenticationRestrictionsOAuth2 server definitionBatch authentication for Web servicesOAuth2 configuration

Principles of OAuth2 authentication

With the OAuth2 authentication method, an application can obtain confidential information about a user. However, you first have to register the application with the OAuth2 server to gain access. To do this, you must specify a redirect URI (described below), and the data the application will obtain from the server. This only has to be done once. The OAuth2 server will then provide you with a client ID and a client secret.

Assuming the application has been registered, the following process unfolds when a user logs in:

  1. The application redirects the user to the OAuth2 server, and provides them with the client ID obtained during the registration.
  2. The OAuth2 authorization server asks the user to log in, unless they are already logged in to the OAuth2 server.
  3. The OAuth2 authorization server asks if data can be shared with the application.
  4. If the user says yes, the OAuth2 authorization server sends an authorization code to the redirect URI that was registered before. This authorizes the application to share the user's data.
  5. The application authenticates by sending the authorization code, together with the client ID and the client secret, to the OAuth2 authorization server.
  6. If the data is correct, the OAuth2 authorization server replies with an access token that allows the application to obtain confidential data (for example the user name). This step is transparent to the user.

The user can then start using the application, as long as their corresponding user entity is marked for OAuth2 authentication with this particular server.

Global configuration

The configurations below are necessary for the authentication.

Restrictions

If you want to perform OAuth2 authentication with a Google account, the server needs to have a public IP address (and not a local IP address on a local area network).

OAuth2 server definition

Name

Name used to reference the OAuth2 setup.

Display name

User-friendly description.

Active

If the check box is cleared, the server is considered as inactive, and no additional login is possible using this setup.

OAuth2 server URL without path

Defines the protocol, server name, and port of the OAuth2 authorization server. This property is automatically set based on the value of "accessTokenUrl" (described below).

URL for authorization

URL used for redirection to the OAuth2 authorization server to allow the user to log in.

URL to get access token

URL used to contact the OAuth2 server to get the access token.

OAuth2 Client Id

Client ID obtained during the application registration.

OAuth2 Client secret

Client secret obtained during the application registration.

Scope for OAuth2 requests

Data the application wants to obtain from the OAuth2 server (defined during the application registration).

Batch authentication

Refer to Batch authentication for Web services.

Redirect path for OAuth2 server

Redirection URI used by the OAuth2 server to send the authorization code to the application server. Note that it contains the name of the OAuth2 server.

URL for requesting user data

URL used to request data from the OAuth2 resource server using the access token.

User field in user name answer

Name of the field within the JSON structure that contains the user name (if JSON is the URL requesting user data). The default value is "user". The "login" attribute (or the "email" attribute) of the corresponding user entity must match exactly the value of the field entered here (not the "authentication name" attribute).

URL for logout

This field stores the OAuth2 URL called when the user logs out from his session. It also allows changing your account when logging back on Sage X3.

For example, if using Sage ID: https://id.sage.com/v2/logout.

You can set the exact page on which you want to log back in by adding values at the end of the URL. Enter the following link in the field:
https://id.sage.com/v2/logout?returnTo{login-page}&client_id={client-id}, where:

URL for user account management

This URL allows you to manage your user account. From your user profile page, you can click the Manage account link to access your OAuth2 user account settings.

Batch authentication for Web services

No interaction is possible when a Web service uses OAuth2 authentication. The Web service can send an access token directly in the Authorize header of the request (example: "Bearer xyzabc123456"). The request must contain an "oauth2" parameter whose value is the name of the OAuth2 instance. The batch authentication flag also has to be set. The server is then given the access token.

Note: In the nodelocal.js configuration file, the "auth" field of the "session" section must contain the "bearer" authentication method. An error is triggered if the access token has expired.

When the OAuth2 server instance is only necessary for batch authentication (SageId server), only the URL for requesting user data and the User field in user name answer are relevant. Other fields can be arbitrary.

OAuth2 configuration

In most cases, all users authenticate in the same way. A global settings function defines the type of standard authentication, namely:

For each user, the authentication rule can be specified as an exception in the users definition, and the Authentication field can have the following values:

In any case, the user has to select the correct authentication method from the login screen.

Refer to Setting Up a Microsoft Account SSO for OAuth2 and Setting Up a Google Account SSO for OAuth2 for more information.