Configuring OAuth2 authentication for API access

Overview

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

The Delphix Engine 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)
`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`
`enabled`	Specifies 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).
`tokenSkewTime`	Specifies the maximum time difference (in seconds) allowed between the validity period of a JWT and the engine's current time.	`60`
`userIdClaim`	Specifies 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`

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.

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
CODE
```
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
CODE
```
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
```

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

Virtualization API Example

CODE

curl -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

CODE

$ 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.