.. include:: /includes.rst.txt .. comments - headings # with overline, for parts * with overline, for chapters = for sections - for subsections ^ for subsubsections " for paragraphs * for H5 + for H6 .. _oauth_authentication: 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 :ref:`edg_as_oauth_client` for configuring EDG as an OAuth client. .. figure:: _images/oauth_client_credentials_flow.png :alt: OAuth 2.0 Clent Credentials Flow :align: center :class: edg-figure-m **OAuth 2.0 Client Credentials Flow** Considerations ^^^^^^^^^^^^^^ * With OAuth, API clients that can access EDG are managed in the identity provider. With :ref:`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 :ref:`oidc_authentication` 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 .. _edg_as_resource_server: 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 :ref:`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: .. code-block:: yaml 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 :ref:`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 :ref:`securityRoles `. Example `oauth2.yaml` file for Okta """"""""""""""""""""""""""""""""""" .. code-block:: yaml authorizationServer: https://your.okta.com/oauth2/default attributeMappings: role: cid Example `oauth2.yaml` file for Amazon Cognito """"""""""""""""""""""""""""""""""""""""""""" .. code-block:: yaml 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 """"""""""""""""""""""""""""""""""""""""""""""""" .. code-block:: yaml 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 ^^^^^^^^ * :ref:`Python example for API client authentication <113-oauth_based_authentication>` * `Other Python examples `_ * :ref:`edg_as_oauth_client`