OAuth 2.0 Authentication

RS Gateway can authenticate clients (such as customer relationship management (CRM) software) with single sign-on using OAuth 2.0. The information here describes a generic implementation. For information about OAuth 2.0 and third-party identity and access management applications, see the discussion about OAuth 2.0 identity and access management.

When OAuth 2.0 is configured:

  • You do not need to configure API client credentials in the RS Gateway.
  • API client credentials are stored with the authorization server and not in the RS Gateway.
  • The authorization server provides a JWT that can carry a set of claims such as a username, email, and roles and groups. If a user exists in the authorization server and in the rsgateway_users.yaml file and is assigned more roles in that file, the roles are merged and all are authorized.
  • You can use varied and strong authentication methods (user/password, MFA, PKI, and so forth) supported by the authorization server.
  • OAuth responses are cached for 5 minutes to reduce latency.
Before configuring RS Gateway for OAuth 2.0 security, you must have the access token, the client must be configured to include the token, and the authorization server must be configured. To configure RS Gateway:
  1. Set the location of the authorization server in the rsgateway-site.yaml file.
  2. Include the access token in requests to RS Gateway.
  3. (Optional) Specify more Spring Security granted authorities.
Figure 1 shows how MATRIXX Backoffice Customer Tool is authenticated using OAuth 2.0 authentication.
Figure 1. RS Gateway OAuth 2.0 Authentication

JSON Web Tokens

Tokens are sent in JSON Web Token (JWT) format. The standard JWT consists of a header, payload, and payload definitions. An encoded JWT is passed to RS Gateway in the authorization header: 
Authorization: Bearer <token>
.
The RS Gateway uses the resourceserver.jwt.issuer-uri value specified in rsgateway-site.yaml to identify the authentication server. For example:
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://ip-address/oauth2/default
Note:
  • The JWT server must be running when the RS Gateway makes the request.
  • The keyset is cached for five minutes. If the authentication server is unavailable when RS Gateway attempts to get an updated keyset, all inbound JWT requests fail with a 500 (Internal Server Error) response until RS Gateway gets an updated valid keyset from the authentication server.
  • If an inbound JWT request has an unidentified key-id (claim kid) RS Gateway attempts to reload the keyset cache. If that does not result in a match for the key-id the request returns a 401 (Unauthenticated) response.
By default the sub value in the JWT is used as the username. You can configure the rsgateway-site.yaml file to use the jti field in the JWT instead of sub. Define the principal-claim-name as shown here:
mtx:
  oauth2:
    roles-converter:
      principal-claim-name: jti

Now, the jti field in the JWT is used as the username instead of the sub value.

In addition, you can configure the rsgateway-site.yaml file to use the groups field in the JWT to define the groups assigned to the user. Define the json-ptr-expr field as shown here: 
mtx:
  oauth2:
    roles-converter:
      json-ptr-expr: /groups

Where /groups is the name of an array of roles defined in the JWT.

These roles are merged with any roles configured in rsgateway_users.yaml and then all roles are authenticated.

For example, a JWT might include the following claims:
// header
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "CM2WQwQyLFguD9_0vGowm"
}
// body
{
  "iss": "964d462e-bf1b-4a1d-b6d0-f66633aead06",
  "sub": "a2953918-0881-4071-a48c-aa774b230d29",
  "aud": "rsgateway",
  "groups": [
    "RSG_READ",
    "RSG_WRITE",
    "RSG_DEBUG"
  ],
  "exp": 1565274257,
  "jti": "05fabd80-afc7-4636-b11e-ad948392c347",
  "scope": "read:client_grants create:client_grants delete:client_grants update:client_grants
}
The fields hold the following information:
  • iss — Issuer is the principal that issued the JWT.
  • sub — Subject is a user name configured in the authorization server.
  • aud — The type of the producer.
  • groups — An array of roles assigned to the user.
  • exp — The value of when the token expires.
  • jti — The field defined in the rsgateway-site.yaml that is used as the login name instead of sub.
  • scope — A space-delimited list of role maps. You can define a scope string to a role in the rsgateway_users.yaml file. If the roles in the token are defined in rsgateway_users.yaml, they are added to the current session established for that user.