Registering OAuth clients

Depending on your application type, you must register your application as a native or a non-native OAuth client. After you register a client, configure additional settings for that client; for example, the token timeouts for the client application.

To use an OpenID Connect protocol for the OAuth client, additionally, generate JSON Web Keys (JWK) and specify the OpenID Connect Issuer URL. The URL  must correspond to the current FQDN of the tenant so that the BMC Helix SSO server can sign the id_token, and the OpenID client can check the id_token signature.

To register a non-native OAuth client application

1. In the administrator console, click OAuth2 > Clients > Register Client.

2. Complete the following fields:

   Field	Description
   Client Name	Specify a name for the client.
   Enabled	Select this check box to enable the client to be authenticated.
   (Optional) Token Exchange	Select this check box to enable the client to request and obtain security tokens from the authorization server.
   List of Redirect URIs	Click Add Redirect URI and add the URI to which the authorization code is sent after an /authorize request is successful. The client-side must support the URI. The Redirect URIs are different for third-party clients and for BMC Helix SSO agents that act as OAuth clients. The client is registered after you click Save, and the certificate is enabled and URIs are parsed successfully after you click Back to return to the existing client list Important: When adding multiple URIs, ensure that a URI value does not exceed 2000 characters. To enable multiple domain support when the BMC Helix SSO agent is configured as OAuth2 client, apply the following default pattern in the Redirect URIs field: http(s)://<application.domain>:[port]/[path]/_rsso/oauth/callback
   (Optional) Trusted clients	Add OAuth client IDs that are eligible to validate tokens issued for the current OAuth client.
   (Optional) openid (Scope used for OpenID Connect)	Select this check box to enable the OAuth client to use the OpenID Connect protocol. This option must be enabled for a client application that uses OpenID Connect for communication. Important: You must enable this setting to authenticate users using applications hosted on different domains using the same BMC Helix SSO server. You must enable this setting to authenticate clients hosted on different domains that use the same BMC Helix SSO server.
   (Optional) Token timeouts	Configure the user session timeout values for access and refresh tokens issued for an OAuth client. The values defined take precedence over the tenant-level OAuth token timeouts defined.  Select the Use custom token timeouts check box, and configure timeout values.

3. (Optional) To make the client multitenant, add the following values:

   Field	Description
   Multi-Tenant client	Select this check box to configure the client application as multitenant. Important: You can configure the client as multitenant only for the SaaS tenant.
   Tenant Name	Click Add Redirect URI, then select a tenant from the Tenant Name list before adding the redirect URI. For each tenant that you add, you must specify the redirect URI.

4. Click Save.

   The following information is automatically generated when you register a non-native client:

   Automatically generated information	Description
   Client ID	Registers the client identifier issued to the client by BMC Helix SSO server during the registration process. You can view this information when you select the registered client, and click to view its details.
   Client Secret	The client secret (private key) is shown only after you click Save.  The private key is used to sign the Java Web Token (JWT) which contains the client authorization. This JWT is different from the one containing the end user credentials which is used in the JWT assertion grant type. Important:  Make a note of the Client Secret because the value is displayed only after you save the configuration.
   Certificate	The certificate contains the public key. Select the registered client to view the certificate value and click to view its details.

To manually generate a new client secret key for a non-native client

You can manually generate client secret keys for existing and non-native clients. You can create a new key if you lose the auto-generated secret key or if your third-party application does not support the length of the auto-generated key.

To generate a new client secret key, perform the following steps:

1. Open the existing client registration for which you want to create the secret key by clicking the Edit icon.
2. In the Additional secrets section, click Add secret.

3. In the New Secret dialog box, update the secret key as required, and click Confirm.

   Important

   • Before you click Confirm, save the key because after you confirm the key, it is obfuscated.
   • You can add only 3 secret keys for a client.
   • The new secret key should be in the ASCII format without spaces and in the range of 36-256 characters.

   The newly generated key is displayed in the Additional secrets section, as shown in the following image:
   

4. On the client registration page, click Save.
5. (Optional) To delete a secret key, in the Additional secrets section, click Delete next to the secret key.

To register a native OAuth client

1. In the administrator console, click OAuth2 > Clients > Register Client.

2. Enable the settings and specify the fields:

   Field	Description
   Client Name	Registers the client name specified during the registration process. This could be any name of the administrator's choice.
   Native (Public) Client	Select this check box to register the OAuth client as a native application client.
   Enabled	Select this check box to enable the client for authorization.
   Token Exchange	Select this check box to enable the client to request and obtain security tokens from the authorization server.
   Redirect Path(s)	Enter a callback path for the native client. If you are using a Developer Studio native client, type callback in this field, and click Add to automatically generate the following loopback interfaces: http://127.0.0.1/>—the generated link corresponds to the IPv4 protocol specification. http://[::1]/<RedirectPath> —the generated link corresponds to the IPv6 protocol specification.
   Client Realm	Select the Realm for which you are registering the native application client.
   (Optional) Trusted clients	Add Auth Proxy to validate access tokens issued by external clients.
   (Optional) openid (Scope used for OpenID Connect)	Select this check box to allow the client to use the OpenID Connect protocol. Enable this setting if the client uses OpenID Connect for communication. Important: You must enable this setting to authenticate clients hosted on different domains that use the same BMC Helix SSO server.
   (Optional) Use custom  token timeouts	Configure the user session timeout values for access and refresh tokens issued for an OAuth client. The values defined take precedence over the tenant-level OAuth token timeouts defined.  Select the Use custom token timeouts check box, and configure timeout values.

3. Click Save.
   The following information is automatically generated when you register a native client. You can view it later at any time:

   Field	Description
   Client ID	BMC Helix SSO server issues the client identifier to the client during the client registration process.
   Native Client Secret	The native client secret is generated during the registration of the native client. You can change the native client secret at a later time if you want to share a common secret between several OAuth native clients.