OAuth2
| Administration Page | Application/Contract | Syracuse/Collaboration | class | oauth2s | Representation | oauth2 |
|---|
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 authentication | Restrictions | OAuth2 server definition | Batch authentication for Web services | OAuth2 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:
- The application redirects the user to the OAuth2 server, and provides them with the client ID obtained during the registration.
- The OAuth2 authorization server asks the user to log in, unless they are already logged in to the OAuth2 server.
- The OAuth2 authorization server asks if data can be shared with the application.
- 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.
- The application authenticates by sending the authorization code, together with the client ID and the client secret, to the OAuth2 authorization server.
- 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:
- {login-page} is the Syracuse login page URL
- {client-id} is the OAuth2 client ID
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:
- Using a database, if no line has been defined in this setup.
- Using an OAuth2 server, if there is an entry giving the OAuth2 server code.
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:
- Standard authentication, which uses the default value defined in the global settings
- Using an OAuth2 server, if you enter the OAuth2 server data
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.