Hybrid OAuth2 Domain

TDV supports a Hybrid OAuth2 domain to enable the use of existing group privileges that are configured in other domains, for example, LDAP. To create a hybrid OAuth2 domain, follow these steps:

1. Launch Manager.
2. From the SECURITY tab, choose Domain Management.
3. Click Add Domain.
4. Enter the Domain Name. The domain name will be part of the login.

When the process of adding the domain is complete, this name is displayed in the Domain Name column and as part of the login (lower case only).

5. Specify the domain type as Hybrid OAuth2.
6. The table below describes the different fields in the New Domain window for the OAuth2 Domain. The values for some of the fields are available in the metadata that your IdP provides when you register TDV as an application. Refer to TDV to IdP Field Mapping for more information about the IdP specific fields.

Field

Description

Domain Name

The name of your domain.

Domain Type

The domain type. Choose Hybrid OAuth2 to create a hybrid OAuth2 domain.

Issuer Value

Issuer indicates who issues the OAuth tokens. It typically matches with the value that appears in the oauth discovery url (For example, https://xyz-374535.okta.com/well-known/openid-configuration)

It is a unique value in a TDV domain and therefore you cannot create two domains with the same issuer value.

This is a required field.

User ID Claim

This is an optional field. However, entering the keyword "preferred_username" in this field will enable the user to login to the TDV applications (TDB Web UI, Studio and Manager) using the user name tied to the OAuth account.

Issuer Claim

Indicates the domain binding claim name. If this is not set, “iss” is the default value. This field is used to receive tokens that do not carry an “iss” claim.

Group Claim

Indicates the key that is part of the token and holds the different groups defined in TDV. Refer to the section Claim Management for Hybrid OAuth2 Domains for information about how to add the TDV claims in your IdP.

Group Format

The domain and principal given in a specific format. if left blank, the default format is domain/principal. A delimiter is required.

Group Separator

Indicates the separator used in the list of TDV groups. The default is space.

Validation

The method used for validating the token. It can be Secret, Public Key or JWKS.

JWKS - JSON Web Key Set endpoint containing information about public keys. The public keys are used to verify the JSON Web Token (bearer token) issued by the authorization server.

Secret - The Secret is part of the signature in the bearer token. The signature is a hash generated by a cryptographic algorithm looking at the header and payload. The hash will be used to verify that the token created by the authorization server has not been tampered.

Public Key - This is the authorization server’s Public Key. Public keys are in JSON Web Key (JWK) format and is used to verify the bearer token issued by the authorization server.

Claim Info

JSON: The specific Claim as a name and value pair in JSON format, for which you can assign privileges and define rules and policies to access the published TDV resources. Multiple Claims can be given as comma-separated. The Claim values can also be in an array.

URL: The Claim Info Endpoint is an OAuth2 protected resource that returns Claims about the authenticated End-User.

Auth URL

The authorization URL. This is part of the endpoint metadata.

Token URL

The token URL. This is part of the endpoint metadata.

Client Secret

The client secret is provided by your Identity Provider. Contact your organization’s administrator to find the Client Secret.

Client ID

The client id is provided by your Identity Provider. Contact your organization’s administrator to find the Client Id.
Scope

Authorization scope, which is typically limited to the protected resources under the control of the client or as arranged with the authorization server (IdP). Limited scope is necessary for an authorization grant.

Format: one or more strings, separated by spaces.

In the IdP, scopes are defined when registering an application (TDV). This is usually done by your organization's administrator. TDV requires ‘openid’ scope at minimum and this is the default value when scope field is empty in TDV domain config.

Annotation

This is an optional description for the domain.
7. Click OK.

Claim Management for Hybrid OAuth2 Domains

Hybrid OAuth2 domains enable the use of existing groups (claims) and the group privileges that are configured in other TDV domains. To do this,

  1. Create a domain in TDV using the TDV Manager tool.

  2. Create groups(claims) for the domain and assign priveleges.

  3. Open your IdP's Claim Management page for the registered TDV application.

  4. Add the Claim(s) that you have created in TDV. Qualify the claim name with the domain name. If there are multiple claims from different domains, use a delimiter.

    For more details aboutadding Claims in your IdPs, refer to your IdP documentation:

    Okta - https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/
    Auth0 - https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims
    Azure AD - https://learn.microsoft.com/en-us/azure/architecture/multitenant-identity/claims

  5. Create a Hybrid OAuth Domain using the instructions provided for the fields in the above section Hybrid OAuth2 Domain

  6. In the Group Claim field, enter the Claim name as defined in the IdP.

  7. In the Group Format field, enter the format you have used to define your domain-claim name (For example, composite@admin, composite/admin)

  8. In the Group Separator field, enter the delimiter you have used in the Group Claim field (For example, ":" or "," or something else.

  9. Once other fields are entered Click on OK to save the Hybrid OAuth2 Domain.