Configuring OAuth2 Authentication for API Access
Configuration / User and Authentication Management / Authentication Mechanisms / Configuring OAuth2 Authentication for API Access

Overview

This article provides instructions on how to set up Open Authorization 2.0 (OAuth2) on the 6.0.11 Delphix Engine. OAuth2 offers an alternative, password-less authentication method for API access to the Delphix Engine.

Delphix Engine (Masking and Virtualization) version 6.0.11 supports authentication using JSON Web Tokens (JWTs) issued by a known authorization server or identity provider (IdP). It is necessary for JWTs to contain a claim that can be used to associate an authentication request with a user that exists in the Delphix Engine. This article describes how to configure the Delphix Engine to validate tokens and associate token claims with Delphix Engine users.

The authentication feature described in this section differs from the API token authentication feature supported by Delphix Engines registered with Data Control Tower (formerly Central Management). For more information on API token authentication, refer to Data Control Tower.

Configuration Options

The following options for configuring OAuth2 for the Delphix Engine are available in the Delphix CLI (as the sysadmin user, under service; oauth2) as well as via the API endpoint /resources/json/delphix/service/oauth2.

OptionDescriptionDefault (if applicable)
audience

Specifies the expected value of the audience claim (aud) of JWTs indicating that the tokens are intended for this particular Delphix engine.

api://delphix
enabledSpecifies whether the OAuth2 feature should be enabled.false
issuerURI(Required) Specifies the base location or identifier of the authorization server (IdP) which the Delphix Engine will use to validate incoming JWTs.
jwkSetURI

Specifies the URI used to retrieve the JSON Web Key (JWK) set, if supported by the authorization server (IdP).


tokenSkewTimeSpecifies the maximum time difference (in seconds) allowed between the validity period of a JWT and the engine's current time.60
userIdClaimSpecifies which claim in a JWT should be used by the Delphix Engine (in conjunction with the userMatchingFieldType setting) to associate a token with a user configured on the Delphix Engine. The default (sub) corresponds to the subject claim of the token.sub
userMatchingFieldType

Specifies which property of a Delphix Engine user will be used to match with the claim (specified in userIdClaim) of a JWT. The Delphix Engine can be configured to match users based on a user's name, emailAddress, or principal properties.

PRINCIPAL

Example of API Access using OAuth2 Token

  1. Obtain a JWT from the Authorization Server (IdP). (The details for this process will vary depending on the IdP vendor.) For the purposes of this example, the contents of the token are stored in the environment variable t.

  2. Access the oauth2-login API endpoint of the Delphix Engine, providing the OAuth2 token. In this example the session information is stored in the file cookies.txt in the working directory. For Virtualization Engines the oauth2-login API endpoint is /virtualization/api/oauth2-login. For Masking Engines the oauth2-login API endpoint is /masking/api/oauth2-login.

    Virtualization API Endpoint Example

    h=<engine address>; curl -i -X POST $h/virtualization/api/oauth2-login -H "Authorization: Bearer $t" -b cookies.txt -c cookies.txt -H 'Content-Type: application/json' -d '{"type": "APISession", "version": {"type": "APIVersion","major": 1,"minor": 11,"micro": 11}}'

    Masking API Endpoint Example

    h=<engine address>; curl -i -X POST $h/masking/api/oauth2-login -H "Authorization: Bearer $t" -H 'Content-Type: application/json' -b cookies.txt -c cookies.txt

  3. Refer to the saved cookies.txt file in subsequent curl invocations. The example below can be used to list the users configured on the Delphix Engine.

    Virtualization API Example

    curl -X GET -b cookies.txt -c cookies.txt -H 'Content-Type: application/json' $h/resources/json/delphix/user

    Masking API Example

    # Store authorization code returned by /masking/api/oauth2-login in $m
curl -i -X GET -b cookies.txt -c cookies.txt -H 'Content-Type: application/json' -H "Authorization: $m" $h/masking/api/v5.1.11/users

User Matching Policy

If the userIdClaim component of a JWT matches more than one Delphix Engine user (for example, if userMatchingFieldType is set to EMAIL_ADDRESS, and the same email address is associated with multiple Delphix Engine users), the oldest user account (by time of creation) will be authenticated.

Suggestion

To ensure all users can be authenticated using OAuth2, make sure that the property specified in userMatchingFieldType is populated and unique for all Delphix Engine users.