Page tree


 

This documentation supports the 22.3 version of BMC Helix Single Sign-On, which is available only to BMC Helix customers (SaaS). 

To view an earlier version, select the version from the Product version menu.

As a BMC Helix Single Sign-On administrator, you might need to configure OAuth 2.0 in any of the following cases:  

  • You have applications that act as OAuth clients and interact with applications protected by BMC Helix SSO.
  • You have applications hosted on different top-level domains that are integrated with the same BMC Helix SSO server. 

Depending on your application type, you need to register a native or a non-native OAuth client. When you have a client registered, you can configure token timeouts for the client application. 

If you are going to use an OpenID Connect protocol for the OAuth client, you must additionally generate JWKs and specify OpenID Connect Issuer URL that must correspond to the current FQDN of the BMC Helix SSO 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. Log in to the BMC Helix SSO Admin Console, and then click OAuth2.
  2. Select Clients, and then click Register Client.
  3. Specify the following fields to register an OAuth client:

    FieldDescription
    Client Name

    Specify any name of your choice.

    EnabledSelect this check box to enable the client for authorization.
    (Optional) Allow Token ExchangeSelect 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 then add the URI to which the authorization code is sent after an /authorize request succeeds. 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.

    To deploy a client on multiple URIs, add multiple URIs separated by commas. After you click Save, the client is registered. When you click Back to return to the list of existing clients, the certificate is enabled, and the URIs are parsed successfully.

    Note: When adding multiple URIs, ensure that each URI 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 Auth Proxy to be able to validate access tokens issued by external clients.

    (Optional) openid (Scope used for OpenID Connect) 

    To enable the OAuth client to use the OpenID Connect protocol, select this check box. Enable this setting if the client application uses the OpenID Connect for communication. If the setting is disabled, the client will not be allowed to use the OpenID Connect.

    Note: You must enable this setting to authenticate users who are using applications hosted on different domains that use 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 timeoutsIf you have the OpenID scope for the OAuth client enabled, you must also configure the user session timeout value. Select the Use custom token timeouts check box, and configure timeout values.
    (Optional) online-refresh (Online refresh)Select this check box to enable auto refreshable access tokens.

    Redirect Path(s)

  4. (Optional) To make the client multitenant, additionally complete the following fields:

    FieldDescription
    Multi-Tenant clientSelect this check box to configure the client application as multitenant. Note: You can configure the client as multitenant only for the SaaS tenant.
    Tenant NameClick Add Redirect URI, and 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.
  5. Click Save.

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

    Automatically generated informationDescription
    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 JWT, which contains the client authorization. This JWT is different from the one containing the end user credentials and which is used in the JWT assertion grant type.
    Certificate

    The certificate is signed with the private key and contains the public key.

    To view the certificate value, select the registered client and click to view its details.

  6. Make a note to save the Client Secret value as this value will not be displayed again.

To register a native OAuth client

  1. Log in to the BMC Helix SSO Admin Console, and then click OAuth2.
  2. Select Clients, and then click Register Client.
  3. Specify the following fields to register an OAuth client:

    FieldDescription
    Client Name

    Registers the client name specified during the registration process. This could be any name of the administrator's choice.

    Native (Public) ClientSelect this check box to register the OAuth client as a native application client.
    EnabledSelect this check box to allow the client for authorization.
    Allow Token ExchangeSelect this check box to enable the client to request and obtain security tokens from the authorization server.
    Redirect Path(s)

    In this field, you must enter a callback path for the native client. If you are using a Remedy DevStudio native client, then you must type callback in this field.

    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 RealmSelect a realm for which you are registering the native application client.
    (Optional) Trusted clients Add Auth Proxy to be able to validate access tokens issued by external clients.
    (Optional) openid (Scope used for OpenID Connect) 

    Select this check box to allow usage of OpenID Connect protocol by the client. Enable this setting if the client uses OpenID Connect for communication. If the setting is disabled, the client will not be allowed to use OpenID Connect.

    Note: You must enable this setting to authenticate clients hosted on different domains that use the same BMC Helix SSO server.

    (Optional) Token timeoutsIf you have the OpenID scope for the OAuth client enabled, you must also configure the user session timeout value. Select the Use custom token timeouts check box, and configure timeout values.
    (Optional) online-refresh (Online refresh)Select this check box to enable auto refreshable access tokens.
  4. Click Save.
    The following information is automatically generated when you register a native client. You can view it later at any time:

    FieldDescription
    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 a registration of the native client. You can change the native client secret at a later time if you need to share the same secret between several OAuth native clients.

To configure the token timeout for OAuth clients

BMC Helix SSO supports long-lived sessions for refresh tokens. Thus, refresh tokens never leave the backend and get visible to the frontend compared to access tokens. It enables refresh token rotation and session prolongation as long as needed. For Auth Proxy, a refresh token is stored in the Redis database where an access token acts as the key. The server gets a refresh token from the Redis DB by using the access token. After that, the refresh token is used for generating a new pair of access and refresh tokens from the server. The long-lived sessions for refresh tokens option is available for the Local type of authentication only. 

To configure the token timeouts for OAuth, perform the following steps:

  1. Log in to the BMC Helix SSO Admin Console. 
  2. Click OAuth2, and then select Settings.
  3. Configure the following fields:

    FieldsDescription

    Access Token Timeout

    Sets a timeout for the access token. After expiration, the issued access token is no longer valid.

    The Access Token Timeout is applied to ID token which is generated when the Opend ID Scope is used.

    Note:

    This setting is not applicable for native clients. The timeout value for access token is specified in the Max Session Time field available in the General > Basic configuration of BMC Helix SSO. 

    Refresh Token Timeout

    Sets a timeout for the refresh token. After expiration, the issued access token is no longer valid.

    Access and refresh tokens remain valid until their expiration. To avoid security concerns, access tokens must be of a short duration. Refresh tokens typically have a longer validity, but cannot be used without providing a valid client id and secret value.

    Note:

    Refresh tokens are not issued for native clients, hence the setting is applicable only for non-native clients.

    OpenID Connect Issuer URL

    If the BMC Helix SSO agent uses the Openid scope to support applications hosted on different domains, you must configure OAuth to use the URL of a server that issues the id_token. Enter the URL that matches the sso-external-url configured in the rsso-agent.properties file. 

Depending on the OAuth client application type, token timeouts can be set differently:

For the Native Client: timeout value for an access token can be specified in the Max Session Time field available in the General>Basic configuration of BMC Helix SSO.
Refresh tokens are not issued for native clients.

For the Single-tenant Client (Client can be registered both in SaaS and Custom Tenant): timeout value for access and refresh tokens can be specified on a tenant level OAuth2>General and will be applied for all Clients in the tenant. The values can be also specified for a Client in the Client settings by selecting Use custom token timeouts checkbox for Token timeouts.

For the Multi-tenant Client: timeout value for access and refresh tokens can be specified in the SaaS tenant level OAuth2>General and will be applied for all Clients in SaaS. For a Client, the values can be specified in the Client settings by selecting Use custom token timeouts checkbox for Token timeouts, and will be applied for all Tenants specified in the Client's redirect URIs. For a tenant specified in Client's redirect URIs if the Use tenant token timeouts for multi-tenant clients feature flag is enabled for the particular tenant, the token timeouts will be taken from the Tenant>Auth2>General.

Important

"Use tenant token timeouts for multi-tenant clients" option has a priority over SaaS General token timeout and
"Use custom token timeouts" option in the Client as well.

       4. Click Save.

To manage list of tokens of OAuth client applications

You can view and delete tokens of active user sessions. You can also refresh the of List of Tokens table.

  1. In BMC Helix SSO Admin Console, click OAuth2.
  2. Select Tokens.
  3. To refresh the list of tokens table, click Refresh.
  4. To invalidate the access token, navigate to the Tokens tab > Action column, and click Delete for the required token.

Write a comment...