Skip to main content

Authentication for REST Web Services

Before proceeding, we strongly recommend reading the Authentication Documentation as it provides essential information on configuring authentication methods. Understanding these fundamentals is necessary to effectively implement authentication for REST web services.

You can specify the authentication type (login type) for a webservice process by setting its property loginTypeId.

The internal login types "internal.none" and "internal.default" are always accessible:

internal_login_types
Figure: Internal login types available by default.

Additional login types can be configured via the instance property loginList. The value assigned to loginTypeId must exactly match one of the entries in the loginList. Note that this value is not selectable from a list but must be entered precisely as configured.

internal_login_types
Figure: Configuring login types via the loginList property.

Requests include a header named authMethod, which can take the following values:

ValueLogin Type
Basicdefault (username & password)
Beareroauth-token
usertokenusertoken

For detailed explanations, see the descriptions of the common login types below:

internal.none​

No authentication is required to access the web service.

internal.default​

This login type requires the user to have the role INTERNAL_WEBSERVICE to authenticate successfully.

Authentication is performed via username and password. The client must send an Authorization header containing the string "Basic " followed by the Base64-encoded "Username:Password".

{
  "header": {
    "authMethod": "Basic",
    "Authorization": "Basic Base64{Username:Password}"
  }
}
info

The Authorization header must be properly Base64 encoded. For example, the string Username:Password is encoded and then prefixed with "Basic " in the header.

OAuth2 token​

This login type also requires the user to have the role INTERNAL_WEBSERVICE.

Configuration details for the "oauth2-token" authentication type can be found here.

Authentication is performed using the Bearer token scheme:

{
  "header": {
    "authMethod": "Bearer",
    "Authorization": "Bearer <token as JSON (not tokenId)>",
    "tokenId": "07e4bee7-0f28-4d8a-aa45-8ec782b27f25"
  }
}

The client obtains a JSON token from Microsoft or another OAuth2 provider, which ADITO verifies by sending it to the provider for validation.

tip

The tokenId represents the unique identifier of the token and is used alongside the Bearer token for authentication.

info

OAuth2 is never listed as a supported authentication method in the Swagger UI, even if it is configured. This is due to technical reasons.

usertoken​

This login type requires the user to have the role INTERNAL_WEBSERVICE.

Configuration for the "usertoken" authentication type is described here.

To authenticate using a usertoken, include the following headers:

  • authMethod with the value "usertoken".
  • tokenId containing the usertoken’s unique identifier.

Example request:

{
  "header": {
    "authMethod": "usertoken",
    "tokenId": "07e4bee7-0f28-4d8a-aa45-8ec782b27f25"
  }
}

In Postman, the request headers will appear as follows:

postman_usertoken_request
Figure: Example of a usertoken authentication request in Postman.