OAuth 2.0 authorization
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 the HTTP service. In addition, OAuth 2.0 supports direct access to the HTTP services by the third-party applications.
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 provided by the resource owner, and issues the access token to the client. In the BMC context, it is the Remedy SSO server.
- Remedy SSO agent—An HTTP request filter to identify unauthenticated requests and redirect those requests to the Authorization server 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 a flow by directing the resource owner's user-agent to the authorization endpoint. The client's request 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 by 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. In the request, 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 with the URI used to redirect the client in step (C). If valid, the authorization server responds 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 grant||Support by native applications||Support by non-native applications||Description|
|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.|
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 the 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 the tokens for clients.
To use the JWT assertion grant type, for a realm with PREAUTH authentication type, import the same certificate as the JWT that contains 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 Connect is a simple identity layer on top of the OAuth 2.0 protocol. OpenID Connect provides the OpenID scope, which can be used with an Authorization code grant type flow. When an OAuth client uses OpenID scope, the Consent page (where an end user allows an OAuth client application to act on behalf of the user) is not displayed to end users.
The following table describes what tokens are returned in the resulting /token call when OpenID scope is used by native and non-native clients:
|Usage of OpenID scope by an OAuth client||Tokens returned for native clients||Tokens returned for non-native clients||Consent page availability to end users|
OpenID scope used
The timeout value for these tokens is set in the Max Session Time field available in the General > Basic configuration of the Remedy SSO server.
The timeout value for these tokens is set in the Access Token Timeout field.
OpenID scope not used
The timeout value for this token is set in the Max Session Time field available in the General > Basic configuration of theRemedy SSO server.
The timeout value for the Access token is set in the Access Token Timeout field available in the OAuth2 > Settings configuration of the OAuth2.
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 key (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 can use any of the available authentication methods at any time.
The Remedy SSO agent can act as an OAuth client to protect applications hosted on different domains. For information about how to configure Remedy SSO agent for applications hosted on different domains, see Connecting the same Remedy SSO agent to different Remedy SSO servers.