Oauth2

When a user starts the application, the user's identity must be known to the application in order to grant him access to the application functionalities or not. Usually the application handles authentication on its own, e. g. using a database or an LDAP server. For OAuth2, authentication is done using an external authentication server, and the application will grant access when authentication with the authentication server has been successful.

Principles of OAuth2 authentication

This authentication is different from database or LDAP authentication methods. It is a method where an application can be granted confidential information about a user.

Before this authentication can be used, the application must have been registered with the OAuth2 server to obtain access. This must be done only once. For the registration, a so-called redirect URI (see below) and the data which the application will obtain from the server, must be provided. The OAuth2 server will give a client ID and a client secret.

Assuming that the application has been registered, when the user logs in, the following process is followed:

1. The application redirects the user to the OAuth2 server first and provides the client ID from the above registration.

2. The OAuth2 authorization server asks the user to log in unless the user is already logged in with the OAuth2 server.

3. The OAuth2 authorization server asks whether the application may obtain the data which has been mentioned in the above registration procedure.

4. If the user approves, the OAuth2 authorization server sends an authorization code to the redirect URI, which has been registered above. The OAuth2 authorization server tells the application that the user is OK and is willing to provide the data.

5. The application has to authenticate with the OAuth2 authorization server by sending the authorization code together with the client ID and client secret (obtained from above registration) to the OAuth2 authorization server.

6. If the data is correct, the OAuth2 authorization server answers with an access token (this part is totally invisible to the user). The access token entitles the application to obtain confidential data - for example the user name (and some other data in the future).

There must be an instance of the user entity for this user, and the user must be marked for OAuth2 authentication with this particular server. Then the user can use the application.

The following global configuration is necessary for this authentication.

Restrictions

When you want to do OAuth2 authentication with a Google account, this will only work if the server has a public IP address (and not a local IP address of a local area network).

OAuth2 server definition

Name

The name used to reference the OAuth2 setup.

Display name

A user-friendly description.

Active

If the check box is cleared, the server is considered "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, for example, https://accounts.google.com. This is the base name that will prefix the next paths.

Path for authorization

This is the path (relative path based on the Oauth2 server path defined above) used for redirection to the OAuth2 authorization server to allow the user to log in. Default value is /oauth/authorize.

Path to get access token

This is the path (relative path based on the Oauth2 server path defined above) used to contact the OAuth2 server to get the access token.

OAuth2 Client Id

This is the client ID obtained from registration of the application.

OAuth2 Client secret

This is the client secret obtained from registration of the application.

Scope for Oauth2 requests

This information is about data that the application wants to obtain from the OAuth2 server (known from above registration).

Batch authentication

see below Batch authentication for Web services.

Path for redirect URI for Oauth2 server

A URL with this path must be registered with the OAuth2 server. Note that it contains the name of the OAuth2 server in its path. The OAuth2 server uses the redirect URI to send the authorization code to the application server.

URL for requesting user data

This is the URL (relative path based on the Oauth2 server path defined above) used to ask for the data from the OAuth2 resource server using the access token.

User field in user name answer

If the answer for the user data requesting URL is JSON, this is the name of the field within the JSON structure that contains the user name. Default value is "user". The login attribute or (email attribute) of the corresponding instance of the user entity must match exactly the obtained field value whose name is entered here (not the authentication name attribute).

Batch authentication for Web services

When a Web service should do OAuth2 authentication, no interaction is possible. The Web service can send an access token directly in the Authorize header of the request (Example for value of header: Bearer xyzabc123456). Since there is no information at all about which OAuth2 server should be used, one server must have the flag batch authentication set. This server will be given the access token. Note that there must not be more than one OAuth2 server with the flag set and that the configuration file nodelocal.js must auth field of the session section must contain authentication method "bearer". There will be an error when the access token has expired.
When the OAuth2 server instance is only necessary for batch authentication (e. g. SageId server), only the following data are relevant (the other can be arbitrary):
* URL for requesting user data
* User field in user name answer

OAuth2 configuration

In most cases, all users authenticate in the same way. There is a global settings function giving the type of standard authentication:

• Using a database if no line has been defined in this setup.
• Using an OAuth2 server if an OAuth2 entry giving the OAuth2 server code has been entered.
• (and some more values)

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 (use the default value given above)
• Using an OAuth2 server (the OAuth2 server data will be provided)
• (and some more values)

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

See also the following document that explains the configuration with Oauth2.