Configuring OAuth 2.0
This topic provides the following information about OAuth 2.0:
OAuth 2.0 (OAuth) is an authorization framework for third-party 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 directs access to the HTTP services by the third-party application.
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 the 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 the Remedy Single Sign-On (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. From Remedy SSO version 19.02, the Remedy SSO agent acts as an OAuth2 Client to support applications hosted on different domains.
OAuth protocol flow
The following diagram depicts the OAuth protocol flow:
The OAuth protocol performs the following process for authorization:
(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 an credential representing the resource owner's authorization.The client receives one of the following authorization grants supported by Remedy SSO.
- Authorization code—In this grant type, the application exchanges an authorization code received from the authorization server for an access token.
- 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.
- JWT assertion—A third-party IdP (Identity Provider) issues a JSON Web Token (JWT), which is signed with a private key. The JWT contains information about the 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 the third-party IdP and Remedy SSO. Hence Remedy SSO can generate access and refresh tokens for client applications.
OAuth client authentication
In earlier versions, Remedy SSO supported OAuth authentication of client applications by using one of the following methods: (a) parameters in the request, (b) HTTP basic authentication schema.
Remedy SSO enables a client application to authenticate itself with Remedy SSO 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.
From version 19.02, the 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.
To configure OAuth
- Click Register Client.
Enter the required OAuth2 details.
Field Description Settings Access Token Timeout
If you enable the OpenID scope for a client, then ensure that you set the Access Token Timeout for managing the user session time.
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.
OpenID Issuer URL Enter the URL of the server issuing the id_token if the 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. Clients Client ID
Registers the client identifier issued to the client by Remedy SSO server during the registration process. This information is prepopulated.
Registers the client name specified during the registration process. This could be any name of the administrator's choice.
Comprises the certificate generated during client registration. The certificate is signed with the private key and contains the public key. This field will be displayed only during client registration and will not be displayed later.
Registers the URI to which the authorization code is sent after a /authorize request succeeds. The URI must be properly handled on the client. The Redirect URIs are different for third party clients and for Remedy SSO agents that act as OAuth Clients.
Add multiple URIs, separted by commas, to deploy a client on multiple different URIs. After you click Save and the registration is successful, when you click Back to list and edit the existing client, the certificate is enabled and the URIs are parsed successfully.
Each URI, seperated by a comma, cannot exceed 2000 characters.
For the multiple domains support when RSSO Agent is configured as OAuth2 client, the following default pattern must be used: http(s)://<application.domain>:[port]/[path]/_rsso/oauth/callback. For more details about this feature, see Configuring multiple domain support.
Enabled Allows the client for authorization. Allowed Scopes openid (Scope used for OpenID connect) Select to allow the OAuth2 client to use OpenID connect.
Note: Ensure you select this check box if you want to authenticate applications hosted on different domains using the same Remedy SSO server.
Tokens List of Tokens
Allows the administrator to search and view the list of valid tokens and refresh the content of the List of Tokens table.
OpenID List of JWks Allows the administrator to view or delete a JWK Id. Generate Allows the administrator to generate a JWK Id.
Note: Ensure you generate a JWK Id if you want to authenticate applications hosted on different domains using the same Remedy SSO server.
- Click Save.
You need to make a note of them because they will not be displayed again.The Client ID and the Client Secret (private key) are generated.
The private key is used to sign the JWT, which contains the client authorization. Note that this JWT is different from the one containing the end-user credentials and which is used in the JWT assertion grant type.
(Optional) To configure Remedy SSO Agent to support applications hosted on different domains:
In the rsso-agent.properties file, set multi-domain-support = true and copy the Client ID and Client Secret generated in Step 6 to this file.
On the OpenID tab, generate the JWK Id.
- (Optional) To use the JWT assertion grant type, create a realm with PREAUTH as the authentication type and 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.
- (Optional) To invalidate the access or refresh the token, in the Tokens tab, click Delete in the Action column for the required token.