22 Using the JSON Web Token Service

After you apply bundle patch 11.1.2.3.161018, Oracle Identity Manager provides a JSON Web Token (JWT) service to simplify the use of Oracle Identity Manager SCIM and REST services.

Note:

For instructions on downloading and applying the 11.1.2.3.161018 bundle patch, refer to the bundle patch documentation.
For information about the Token service API that lets your acquire a JWT token using which user can securely access REST end points, see REST API for Oracle Identity Governance Token Service in the Oracle Identity Management 11g Release 2 (11.1.2.3.0) documentation library. To do so, navigate to the title REST API for Oracle Identity Governance Token Service under the Reference section, at the following URL:

http://docs.oracle.com/cd/E52734_01/cross/allbooksdocs.htm

This section describes how to use the JWT service for Oracle Identity Manager SCIM and REST services. It contains the following sections:

About the JWT Service
Authentication Scenarios
Acquiring and Applying a JWT
JWT-Based OIM Identity Provider for SCIM-REST Authentication
End Point and Application Details

22.1 About the JWT Service

To simplify the use of the Oracle Identity Manager SCIM and REST services in various deployment scenarios, a JSON Web Token (JWT) service is available and used with Oracle Identity Manager. The JWT produced by the Oracle Identity Manager token service contains a subject claim for an OIM user signed by the Oracle Identity Manager server, and can be presented for authentication to the OWSM agent protecting the SCIM and REST services API.

The default multi-token OWSM policy protecting the Oracle Identity Manager SCIM and REST services accept various standard authentication mechanisms. This OIM Identity Provider is targeted towards OIM enterprise deployments not already integrated into an authentication domain, or to augmented authentication mechanisms, such as WebSSO, which do not natively support REST-style APIs. This section describes the various authentication scenarios supported in Oracle Identity Manager deployments for access to the SCIM and REST services. In some instances, an application might be deployed as an extension to the Oracle Identity Manager UI, while other cases suppose an application independent of the Oracle Identity Manager UI and consuming the SCIM and REST services to satisfy some identity requirements. The SCIM and REST consumer can be an HTML5/JS application loaded from a web-tier distinct from that in which Oracle Identity Manager is deployed and running in a browser, or the backend of a JSP or .Net application. Another scenario is a mobile application consuming the SCIM and REST services.

22.2 Authentication Scenarios

The following use cases describe various authentication scenarios as a prelude to acquiring a JWT and accessing the SCIM and REST services:

Stand-alone (no WAM):

According to this use case, authentication is through OIM Portal. Therefore, there is no Oracle Identity Manager UI authentication. Authentication is either of the following:
- Directly to the OIM REST API using Oracle Identity Manager as the identity store
- Some other mechanism, such as OAuth2, in which the subject corresponds to an Oracle Identity Manager username.
OIM domain is WAM-enabled (OAM, SM, TAM):

The user has authenticated to the WAM domain, which is protecting Oracle Identity Manager. The application is in possession of an SSO token containing a subject corresponding to an Oracle Identity Manager usernam, or the SSO agent has set a special request header asserting the username.
Mobile application:

The application will be in possession of a security token, such as OAuth2, containing a subject corresponding to an Oracle Identity Manager username. In all scenarios, OWSM protects the Oracle Identity Manager SCIM and REST services. The OWSM agent is configured with oracle/multi_token_noauth_over_ssl_rest_service_policy.

22.3 Acquiring and Applying a JWT

The Oracle Identity Manager SCIM and REST services are augmented with a JWT identity provider presenting a /iam/governance/token/api/v1/tokens endpoint, through which the application can acquire a JWT for subsequent use at the SCIM and REST services, as shown in Figure 22-1.

Figure 22-1 Token Endpoint Service

Description of ''Figure 22-1 Token Endpoint Service''

OWSM at the /iam/governance/token/api/v1/tokens endpoint authenticates the user and serves as an ID asserter to the /iam/governance/token/api/v1/tokens endpoint implementation. The /iam/governance/token/api/v1/tokens endpoint can issue a token for self, provided the authenticated user has sufficient privileges. The /iam/governance/token/api/v1/tokens implementation validates the target user name, matches an OIM user, and issues a JWT claiming the user name in the HTTP response. This JWT is used for all subsequent access by the application to the Oracle Identity Manager SCIM and REST API.

22.4 JWT-Based OIM Identity Provider for SCIM-REST Authentication

This section describes the JWT-based OIM identity provider for SCIM and REST authentication. It contains the following sections:

SCIM and REST Security Overview
JSON Web Token (JWT)
OIM Identity Provider End Point
Session Timeout and Refresh

22.4.1 SCIM and REST Security Overview

The SCIM and REST services are protected by an OWSM authentication-only policy. On successful access, the policy establishes a context containing a javax.security.auth.Subject containing a weblogic.security.principal.WLSUserImpl principal, and the principal contains the authenticated login ID (OIM user name). The SCIM and REST services are deployed in the Oracle Identity Manager server application, and invoke Oracle Identity Manager service APIs, such as UserManager.createUser via OimClient. The EJB-remoting mechanism converts the WLS login context to an Oracle Identity Manager context, which is subsequently used to identify the caller for authorization and logging purposes.

Note:

The following call can be used to retrieve the Subject:

Subject activeSubject = JpsSubject.getSubject(AccessController.getContext());

22.4.2 JSON Web Token (JWT)

The JSON Web Token (JWT) is defined in RFC 7519. The JWT issued by OIM Identity Provider contains a claim segment for a subject (OIM user), issuer, expiration, and so on.

{"exp":1448420525,"sub":"xelsysadm","iss":"www.oracle.com","prn":"xelsysadm","iat":1448418725}

The JWT also includes an authentication header (JOSE) indicating the algorithm and certificate key used for the JWS computation:

{"alg":"RS256","typ":"JWT","x5t":"8KTfKAncWGbLsNOlLZRQ77qSE74","kid":"xell"}

The header and payload are base64url encoded, concatenated, and separated by a ".". Then the RSA signature is computed over that input, base64url encoded, and appended following a ".". The OIM Identity Provider encapsulates the result in another JSON structure, for example:

{
    "tokenType": "Bearer",
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsIng1dCI6IjhLVGZLQW5jV0diTHNOT2xMWlJRNzdxU0U3NCIsImtpZCI6InhlbGwifQ.eyJleHAiOjE0NDg0MjA1MjUsInN1YiI6InhlbHN5c2FkbSIsImlzcyI6Ind3dy5vcmFjbGUuY29tIiwicHJuIjoieGVsc3lzYWRtIiwiaWF0IjoxNDQ4NDE4NzI1fQ.s6OLNLmYdJXF2Zj6SaTM5vPHOcKuBIcJlBvVmSATCBKnS-_qmvUYn9-8bcXDbEBo9qum2O3kF0SmbtH0u6-rx-QtNXWupf9-vbtAUVoOpm8f6X3tHVbhzBVixKYnwAZC8tN3LJ6UNOhYzxe7iOZfclmhEQILgA7I3J152gToKmU",
    "expiresIn": "1799"
    }

In a subsequent call to the SCIM or REST service, the value of accessToken is submitted in the authentication header, for example JWT, produced via oracle.security.jps.service.trust.TrustService and oracle.security.restsec.jwt.JwtToken.

22.4.3 OIM Identity Provider End Point

This is a REST service deployed in the OIM server context (JVM) at /iam/governance/token/api/v1/tokens.

On successful invocation, it returns a JWT containing a subject claim for an OIM user name. It works in the token-for-self mode, in which the request is processed for the authenticated user; any valid user can request a token for self.

Only POST is supported because allowing GET will expose the user name parameter.

22.4.4 Session Timeout and Refresh

The JWT must include an expiration time, set from a server configuration value. A JWT can be refreshed at the /iam/governance/token/api/v1/tokens service by supplying an unexpired JWT using HTTP PUT method. Therefore, OWSM should be configured to accept both HTTP Basic Auth and JWT for the /iam/governance/token/api/v1/tokens endpoint.

The HTML5/JS (web browser) application must manage token refresh, including recognizing when the application has been idle and stopping the refresh cycle. After the final token expires, the application will re-authenticate through whatever mechanism was previously used.

A mobile application can securely store credentials necessary to acquire a JWT. Therefore, re-authentication does not necessarily require user interaction, even in the case of username/password authentication.

22.5 End Point and Application Details

This section describes the end points and the application details. It contains the following section:

End Point

22.5.1 End Point

This section describes the Token end point and Refresh Token end point. It contains the following sections:

Token End Point ( /iam/governance/token/api/v1/tokens )
Refresh Token Endpoint(/iam/governance/token/api/v1/tokens )

22.5.1.1 Token End Point ( /iam/governance/token/api/v1/tokens )

This end point is exposed for application to get the token for user. OWSM at the /iam/governance/token/api/v1/tokens endpoint authenticates the user and serves as an ID Asserter to the /iam/governance/token/api/v1/tokens endpoint implementation. The /iam/governance/token/api/v1/tokens implementation validates that the target user name matches an OIM user and issues a JWT claiming the user name in the HTTP response. This JWT is used for all subsequent access by the application to the Oracle Identity Manager SCIM and REST API.

This end point is enabled on HTTPS only.

Authorization

Consider the following use case for authorization:

Token-For-Self: Any authenticated user can request a token-for-self. This case is identified by an empty payload in the token request. The target user is the user name identified in the Basic Auth header.

Token End Point Scenario

This section describes the following token end point scenario:

Token-For-Self: Web browser via portal with Oracle Identity Manager as the Identity Store

Token Request (Self)

Request method: POST
URL: https://<host>:<ssl port>/iam/governance/token/api/v1/tokens
Headers:
- Authorization: Basic <Base64 encoded user:password>
- Accept: application/json
- Content-Type: application/json
- X-Requested-By: <random value>

22.5.1.2 Refresh Token Endpoint(/iam/governance/token/api/v1/tokens )

This end point is exposed for application to refresh their existing token by providing old token before they get expired. This end point validates the existing token and then re-issues a token if the existing token is still valid. This end point is protected by JWT OWSM policy.

This end point is enabled on HTTPS only.

Refresh Token End Point Configuration

Table 22-1 shows the Refresh Token end point configuration.

Table 22-1 Refresh Token End Point Configuration

Use Case	Availability	Description
Web browser via portal with Oracle Identity Manager as the Identity Store	Yes	Application gets the token directly by accessing the `/iam/governance/token/api/v1/tokens` end point by providing the user name and password. If the token is about to get expired, then the application should hit the`/iam/governance/token/api/v1/tokens` end point by providing the existing token, and gets a new token.

Refresh Token Request

Request method: PUT
URL: https://<host>:<ssl port>/iam/governance/token/api/v1/tokens
Headers:
- Authorization: Bearer <token value>
- Accept: application/json
- Content-Type: application/json
- X-Requested-By: <random value>