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.0 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
.
Option | Description | Default (if applicable) |
---|---|---|
| Specifies the expected value of the audience claim ( |
|
| Specifies whether the OAuth2 feature should be enabled. |
|
| (Required) Specifies the base location or identifier of the authorization server (IdP) which the Delphix Engine will use to validate incoming JWTs. | |
| Specifies the URI used to retrieve the JSON Web Key (JWK) set, if supported by the authorization server (IdP). | |
| Specifies the maximum time difference (in seconds) allowed between the validity period of a JWT and the engine's current time. |
|
| Specifies which claim in a JWT should be used by the Delphix Engine (in conjunction with the |
|
| Specifies which property of a Delphix Engine user will be used to match with the claim (specified in |
|
These options may also be set in the Delphix Setup application. Please refer to the following procedures for configuring OAuth2 parameters for new or existing Delphix Engines.
![](../../__attachments/131737625/im2.png?inst-v=9f5cd9ef-94fe-4677-b3c4-6c5d1617af5c)
New engine configuration
Follow this procedure to configure OAuth2 on a new Delphix Engine.
Connect to the Delphix Engine at
http://>>
. The Delphix Setup application will launch when connecting to the server.Enter the sysadmin login credentials; this account has a default username of sysadmin and password of sysadmin.
In the Authentication step of the Delphix Setup wizard, check the Use OAuth2 access tokens box and configure the OAuth2 settings as desired. (Refer to the table above for more information on these settings.)
Complete the remaining setup steps as usual.
Existing engine configuration
Follow this procedure to configure OAuth2 on an existing Delphix Engine.
Connect to the Delphix Engine at
http://>>
. The Delphix Setup application will launch when connecting to the server.Enter the sysadmin login credentials.
In the Authentication tile, select Modify.
In the Authentication dialog, check the Use OAuth2 access tokens box and configure the OAuth2 settings as desired. (Refer to the table above for more information on these settings.)
Example of API access using OAuth2 token
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
.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
CODEh=<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
CODEh=<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
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
CODEcurl -X GET -b cookies.txt -c cookies.txt -H 'Content-Type: application/json' $h/resources/json/delphix/user
Masking API Example
CODE# 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
CLI access using OAuth2 token
When OAuth2 is enabled, CLI logins will prompt the user to supply either an OAuth2 access token or a password to authenticate:
CLI Access Prompt with OAuth2 Enabled
$ ssh myengine -l admin
Enter access token or press enter to provide a password:
To authenticate using an OAuth2 token, paste its contents when this prompt is shown. As with API authentication, the OAuth2 token must be current (not expired) and must contain a claim that can be associated with a valid Delphix Engine user, based on the userIdClaim and userMatchingFieldType values set on the Delphix Engine.
To bypass OAuth2 authentication and use password authentication, press Enter when this prompt is shown and a conventional password prompt will be displayed.
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.
HTTPS Proxy Configuration
If the OAuth2 identity provider cannot be directly reached by a Delphix Engine, a HTTPS proxy may be used. The sysadmin user can create or modify HTTPS proxy settings via the CLI/API endpoint service; proxy
, or in the Delphix Setup application by selecting to modify the Outbound Connectivity tile, checking the Configure web proxy box, and entering the host, port, and (optionally) username and password of the proxy server.