Authentication with OAuth 2.0

This section describes how to configure an EDG server to use OAuth 2.0 for authentication. This is an authentication method that API clients can use to authenticate with EDG.

EDG supports authentication with OAuth 2.0 Client Credentials flow. With this flow, API clients request an access token from an Authorization Server, and then use the token to access EDG APIs. The API client and the Authorization Server share a client secret, which is used to authenticate the token request. The only direct interaction between EDG itself and the Authorization Server is the one-time retrieval of a public key that EDG uses to validate tokens. In this flow, EDG is said to be acting as a Resource Server.

EDG itself can also act as an API client that uses OAuth 2.0 authentication, in particular when accessing another EDG instance that requires authentication with OAuth 2.0. For example, to publish to Explorer using OAuth, see EDG as an OAuth API client for configuring EDG as an OAuth client.

OAuth 2.0 Clent Credentials Flow

OAuth 2.0 Client Credentials Flow

Considerations

  • With OAuth, API clients that can access EDG are managed in the identity provider. With HTTP Basic Authentication, they are managed by the EDG administrator in a configuration file.

  • OAuth is more secure than basic since credentials are not sent with every request to EDG

  • OAuth can be complex to implement since it is a multi-step protocol that involves an additional party (the Authorization Server) and there is considerable variation between providers.

End-users logging in directly to EDG cannot use this authentication method. It is for authenticating API clients only. See Authentication with OpenID Connect (OIDC) for a related SSO end-user authentication method.

Prerequisites

  • The EDG administrator must obtain the Authorization Server’s OpenID Provider Configuration URL (ending in /.well-known/openid-configuration).

  • The EDG administrator should obtain all client IDs that will be used to access EDG, to facilitate configuration of access control.

  • The access token issued by the Authorization Server must provide an attribute to be used as the user’s role within EDG

Configuring EDG as a Resource Server

Note

When configuring this method of authentication, it is helpful to have a technical resource familiar with the OAuth 2.0 Authorization Server to assist with the configuration. TopQuadrant is unable to assist with specific configuration options for each customer’s Authorization Server.

To enable OAuth 2.0 authentication, add or uncomment in the setup file (edg-setup.properties):

apiAuthMethods = oauth2

Also, create a oauth2.yaml file according to the following section.

The oauth2.yaml file

By default, the system will look for a file oauth2.yaml in the same directory as the setup file.

If desired, the name and location can be overridden in the setup file:

oauth2ConfigFile = ./my-idp-oauth2.yaml

Syntax

The file uses YAML syntax. It consists of an OAuth 2.0 configuration record of the following form:

authorizationServer: https://your.authorization.server
attributeMappings:
   role: auth-server-role-attribute

A record consits of these elements:

authorizationServer (required)

The base URL for the Authorization Server. This is the part that precedes /.well-known/openid-configuration in the Authorization Server’s OpenID Provider Configuration. See below for examples.

attributeMappings (required)

This maps the attributes returned by the Authorization Server in the access token to attributes understood by EDG. The left-hand values are EDG attributes; the right-hand values are access token attributes.

The following EDG attributes are supported:

role (required)

The access token attribute containing the API user’s group, to be used as an EDG security role. If the token does not provide a suitable attribute, the client ID attribute can be used (see examples below). The group/role name must match one of the securityRoles defined in the setup file.

Note

The service account in EDG that represents the API client will have the token’s sub (subject) as its unique username/login ID.

If the client ID attribute is mapped to role, then any client IDs used to access EDG must be added as securityRoles.

Example oauth2.yaml file for Okta

authorizationServer: https://your.okta.com/oauth2/default
attributeMappings:
   role: cid

Example oauth2.yaml file for Amazon Cognito

authorizationServer: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxxxxxx
attributeMappings:
   role: client_id

Example oauth2.yaml file for Microsoft Entra ID

authorizationServer: https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/v2.0
attributeMappings:
   role: azp

Note

If using Microsoft Entra ID as the Authorization Server, you will need to configure the EDG app registration to use version 2 tokens:

  1. Go to App Registrations in Entra ID

  2. Select the EDG app

  3. Select Manifest

  4. Change

    "accessTokenAcceptedVersion": null,

    to

    "accessTokenAcceptedVersion": 2,

  5. Save

This is due to a bug in Entra ID which affects token validation using third-party JWT libraries. Unless you set accessTokenAcceptedVersion to 2, it will default to issuing version 1 tokens, which use a different issuer ID, which causes validation to fail.

See also