This documentation supports the 19.08 version of Remedy Single Sign-On.

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

Configuring OAuth 2.0

OAuth 2.0 (OAuth) is an authorization framework for web applications and native applications. On behalf of a resource owner, third-party applications use OAuth 2.0 to get limited access to an HTTP service. The framework also enables an approval interaction of the resource owner with HTTP service. In addition, OAuth 2.0 supports direct access to the HTTP services by the third-party application.

OAuth roles

The following roles are supported by OAuth 2.0:

  • Resource Owner—The end user who grants access to protected resources.
  • Resource Server—The server that hosts the protected resources and allows access by receiving an access token from a third-party application. In the BMC context, it is a BMC application.
  • Client—The third-party application that requests access to protected resources on behalf of the resource owner. The client can also be a BMC application that requests resources from another BMC application.
  • Authorization server—The server that authenticates the resource owner, receives the authorization of the client by the resource owner, and issues the access token to the client. In the BMC context, it is Remedy SSO server.
  • Remedy SSO agent—An HTTP request filter to identify unauthenticated requests and redirect those requests to successfully complete Remedy SSO server authentication. Remedy SSO agent acts as an OAuth2 Client to support applications hosted on different domains.

OAuth 2.0 flow

The following diagram depicts the authorization flow for OAuth framework:

The OAuth framework performs the following authorization tasks:

(A) The client initiates the flow by directing the resource owner's user-agent to the authorization endpoint. The client includes its client identifier, requested scope, local state, and a redirection URI to which the authorization server sends the user-agent back after the access is granted (or denied).

(B) The authorization server authenticates the resource owner (via the user-agent) and establishes whether the resource owner grants or denies the client's access request.

(C) Assuming that the resource owner grants access, the authorization server redirects the user-agent back to the client using the redirection URI provided earlier (in the request or during client registration). The redirection URI includes an authorization code and any local state provided by the client earlier.

(D) The client requests an access token from the authorization server's token endpoint by including the authorization code received in the previous step. Access tokens are credentials used to access protected resources and is a string representing an authorization issued to the client. When making the request, the client authenticates with the authorization server. The client includes the redirection URI used to obtain the authorization code for verification.

(E) The authorization server authenticates the client, validates the authorization code, and ensures that the redirection URI received matches the URI used to redirect the client in step (C). If valid, the authorization server responds back with an access token and, optionally, a refresh token. Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical scope.

OAuth grant types

An authorization grant is a credential representing the resource owner's authorization.The client receives one of the following authorization grants supported by Remedy SSO.

Authorization grantSupport by native applicationsSupport by non-native applicationsDescription
Authorization code

yes

yes

In this grant type, the application exchanges an authorization code received from the authorization server for an access token.
Refresh token

remove

yes

Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server, and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical scope.
JWT assertion

remove

yes

A third-party IdP (Identity Provider) issues a JSON Web Token (JWT), which is signed with a private key. The JWT contains information about an end user on behalf of whom the client wants to access resources. A certificate signed with the same private key as in the JWT must be configured in the PreAuth IdP on the Remedy SSO side. This certificate ensures that there is a trusted relationship between a third-party IdP and Remedy SSO. Hence, Remedy SSO can generate access and refresh tokens for clients.

To use the JWT assertion grant type, for a realm with PREAUTH authentication type, import the same certificate as the JWT containing the end-user credentials. The user ID field has to be filled with a value and cannot be left blank even though OAuth automatically uses a claim called sub as the user ID. PREAUTH then validates the signature of the JWT that will be passed to Remedy SSO.

OpenID scope

OpenID Connect  is a simple identity layer on top of the OAuth 2.0 protocol. The OpenID scope, available with the OpenID Connect, can be used with an Authorization code grant type flow. 

OpenID scope used 

When the OpenID scope is used with authorization code grant type flow, in the resulting /token call, the Access token and ID token are returned.

Note

The timeout value for Access token and ID token for native clients is set in the Max Session Time field available in the General > Basic configuration of Remedy SSO server.

The timeout value for Access token and ID token for non-native clients is set in the Access Token Timeout field 


With OpenID scope used, the Consent page where an end user allows OAuth Client to act on behalf of the end user, is displayed to end users.

OpenID scope used

When the OpenID is not used by a non-native client, Access token and Refresh token are returned in the resulting /token call. When the OpenID is not used by a native client, only the Access token is returned in the resulting /token call. 

Note

The timeout value for Access token for native clients is set in the Max Session Time field available in the General > Basic configuration of Remedy SSO server.

The timeout value for Access token for non-native clients is set in the Access Token Timeout field available in the OAuth2 > Settings configuration of the OAuth2.

With OpenID scope not used, the Consent page where an end user allows OAuth Client to act on behalf of the end user, is displayed to end users.

OAuth client authentication

Remedy SSO enables a client application to authenticate itself with Remedy SSO by using the JWT assertion. The JWT contains information about the client application and must be signed with a client secret (also known as private key) that is shared with the client application during registration. Remedy SSO then validates the client application by using the certificate generated by Remedy SSO.

Though the client authentication method can be used with any of the grant types provided by OAuth, usage of client authentication with a grant type is not mandatory. A client application is free to use any of the available authentication methods at any time.

Remedy SSO agent acts as an OAuth2 client to protect applications hosted on different domains. For more information on configuring Remedy SSO agent for supporting applications hosted on different domains, see Configuring Remedy SSO agent.

Configuring OAuth clients

You can perform the following tasks to configure OAuth clients:

To register a non-native OAuth2 client application

  1. Log in to Remedy SSO Admin Console, and then click OAuth2.
  2. Select Clients, and then click Register Client.
  3. Complete the following fields to register a client:

    FieldDescription
    Client Name

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

    EnabledAllows the client for authorization.
    Redirect URIs

    Registers the URI to which the authorization code is sent after an /authorize request succeeds. The URI must be properly handled on the client side. The Redirect URIs are different for third party clients and for Remedy SSO agents that act as OAuth Clients.

    To deploy a client on multiple different 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.

    Each URI, separated by a comma, cannot exceed 2000 characters.

    For the multiple domains support when Remedy SSO agent is configured as OAuth2 client, apply the following default pattern: http(s)://<application.domain>:[port]/[path]/_rsso/oauth/callback. For more details about this feature, see Configuring multiple domain support.

    openid (Scope used for OpenID connect) (Optional)

    To allow usage of OpenID Connect protocol by the OAuth client, 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 using the same Remedy SSO server. When you have the OpenID scope for the OAuth client enabled, you must also configure the user session timeout. Configure the Access Token Timeout field to specify the timeout value of the ID token and Access token.

  4. 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 Remedy 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. Important: You must make a note and save the Client Secret value because it will not be displayed again.

    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. You can view the certificate value when you select the registered client, and click to view its details.

  5. Make a note to save the Client Secret value.

To register a native OAuth2 client

  1. Log in to Remedy SSO Admin Console, and then click OAuth2.
  2. Select Clients, and then click Register Client.
  3. Complete the following fields to register a client:

    FieldDescription
    Client Name

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

    EnabledEnable the client to allow the client for authorization.
    Native (Public) ClientSelect this check box to register the OAuth client as a native application client.
    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/<RedirectPath>—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.
    openid (Scope used for OpenID connect) (Optional)

    To allow usage of OpenID Connect protocol by the client, select this check box. Enable this setting if the client 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 clients hosted on different domains using the same Remedy SSO server.

    When you have the OpenID scope for a native client enabled, you must also configure the user session timeout. Configure the Max Session Time field to specify the timeout value of the ID token and Access token.

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

    FieldDescription
    Client ID

    Remedy SSO server issues the client identifier to the client during the client registration process.

    Native Client SecretThe native client secret is generated during a registration of the native client.

To configure the token timeout for OAuth clients

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

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

    Note:

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

    OpenID Issuer URL

    Enter the URL of the server issuing the id_token if Remedy SSO agent is configured for using the Openid scope to support applications hosted on different domains. Ensure this URL matches the External URL that is configured in the rsso-agent.properties file.

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 Remedy SSO Admin Console, click OAuth2.
  2. Select Tokens.
  3. To refresh the list of tokens table, click Refresh.
  4. To invalidate the access token, in the Tokens tab, click Delete in the Action column for the required token.

To generate JWKs for OAuth flow

To support multiple domain applications when Remedy SSO server is used as an OAuth server, and Remedy SSO agent is used as an OAuth client, you need to gerenare JWK. 

  1. Log in to Remedy SSO Admin Console. 
  2. Click OAuth2, and then select OpenID.
  3. Click Generate to authenticate applications hosted on different domains using the same Remedy SSO server.


Access Token Timeout
Was this page helpful? Yes No Submitting... Thank you

Comments