Using the JSON Web Token Service

21.1 About the JWT Service

The JSON Web Token (JWT) service simplifies the use of Oracle Identity Governance SCIM and REST services in various deployment scenarios.

The JWT produced by the Oracle Identity Governance token service contains a subject claim for an OIM user that is signed by the Oracle Identity Governance server. This claim can be presented for authentication to the OWSM agent that protects the SCIM and REST API.

The default multitoken OWSM policy protecting the Oracle Identity Governance SCIM and REST services accepts various standard authentication mechanisms. This OIM Identity Provider is targeted towards OIG enterprise deployments that are not already integrated into an authentication domain, or to augmented authentication mechanisms, such as WebSSO, which do not natively support REST-style APIs. This document describes the various authentication scenarios that are supported in Oracle Identity Governance deployments for access to the SCIM and REST services.

In some instances, an application might be deployed as an extension to the Oracle Identity Governance UI, while in other cases, an application that is independent of the Oracle Identity Governance UI uses the SCIM and REST services to satisfy identity requirements. The SCIM and REST consumer might be an HTML5/JS application that is loaded from a web-tier distinct from that in which Oracle Identity Governance is deployed and running in a browser, or it might be the backend of a JSP or .Net application. A mobile application might also consume SCIM and REST services.

21.2 Authentication Scenarios

An application can acquire JWT and access SCIM and REST services in various authentication scenarios, such as a stand-alone deployment or a mobile application.

The following use cases describe various authentication scenarios that precede acquiring a JWT and accessing the SCIM and REST services:

Stand-alone Oracle Identity Manager UI authentication (via WLS and OIM Identity Store; no WAM):

A user who is already authenticated by the Oracle Identity Manager UI login page has access to the REST and SCIM API (through a separate HTML5/JS application) without having to authenticate again.
Stand-alone (no WAM):

Authentication is through OIG Portal. Oracle Identity Manager UI authentication does not take place. Authentication takes place using either of the following:
- Direct authentication to the OIG REST API using Oracle Identity Manager as the identity store
- Authentication using another mechanism, such as OAuth2, in which the subject corresponds to an Oracle Identity Manager username.
WAM-enabled OIM domain (OAM, SM, and TAM):

The user has authenticated to the WAM domain, which protects Oracle Identity Manager. The application has an SSO token whose subject matches an Oracle Identity Manager user name, or the SSO agent has set a special request header that asserts the user name.
Mobile application

The application has a security token, such as OAuth2, whose subject matches an Oracle Identity Manager user name. In all scenarios, OWSM protects the Oracle Identity Manager SCIM and REST services. The OWSM agent is configured with http_jwt_token_ service_policy.

21.3 Acquiring and Applying a JWT

The Oracle Identity Manager SCIM and REST services are augmented with a JWT identity provider that presents an endpoint in /iam/governance/token/api/v1/tokens.

Through this endpoint, the application can acquire a JWT for subsequent use with SCIM and REST services, as shown in Figure 21-1.

Figure 21-1 Token Endpoint Service

Description of "Figure 21-1 Token Endpoint Service"

In some scenarios, the application interacts directly with the /tokens endpoint. In other scenarios, the application is protected by an external authentication mechanism, and the user's credentials are not available to the application. For example, suppose a user authenticates to the Oracle Identity Manager UI by opening a SCIM or REST-based application that augments the Oracle Identity Manager UI, and expects to proceed without re-authenticating. To accommodate such configurations, a façade token service that is deployed within the application's authentication domain facilitates the acquisition of a JWT that corresponds to the user. The token façade has an OWSM SAML client policy applied. It extracts the user account from the session and creates a SAML token that is used for authentication at the token endpoint. Then, the token service generates a JWT token for the logged-in user. The JWT is returned to the application. When an application that is authenticated on behalf of a user invokes the façade web app (/iam/governance/token/api/v1/tokens), the web app can retrieve a JWT from the service and relay it back to the application, as shown in Figure 21-2.

Figure 21-2 Token Facade Web App

Description of "Figure 21-2 Token Facade Web App"

At the /tokens endpoint, OWSM authenticates the user and asserts the ID to the /tokens endpoint implementation. If the authenticated user has sufficient privileges, the endpoint can issue a token for self. The implementation validates the target user name, matches an OIM user, and issues a JWT that claims 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.

By default, the façade web application is deployed with Oracle Identity Manager.

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

The JWT-based OIM Identity Provider for SCIM and REST authentication issues the JWT. It also includes SCIM and REST security, an identity provider endpoint, and session timeout and refresh.

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

21.4.1 Overview of SCIM and REST Security

The SCIM and REST services are protected by OWSM authentication-only policies that are specific to the REST services. They are also protected by OPSS authorization policies that are common to accesses to OIM entities from any service.

The default OWSM authentication-only policy configured for the SCIM and REST services accepts the JWT produced by the token service, among other authentication mechanisms. See Understanding Global Policy Attachments for information about OWSM policy attachments and the default Oracle Identity Manager policies.

21.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 other data.

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

The JWT also includes an authentication header (JOSE) that indicates 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 period character (.). The RSA signature is computed over that input, base64url encoded, and appended following a period character. The OIM Identity Provider encapsulates the result in another JSON structure that resembles the following:

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

In a subsequent call to the SCIM-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.

21.4.3 The OIM Identity Provider Endpoint

The OIM Identity Provider endpoint is a REST service deployed in the OIM server context (JVM) in /iam/governance/token/api/v1/tokens.

When the endpoint is invoked, it returns a JWT that contains a subject claim for an OIM user name.

In token-for-self mode, the request is processed for the authenticated user. Any valid user can request a token for self.

21.4.4 Session Timeout and Refresh

The JWT must include an expiration time that is 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 the 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 stopping the refresh cycle when the application has been idle. After the final token expires, the application reauthenticates through whatever mechanism was previously used.

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

21.4.5 Configuring JWT Timeout Period

The JWT timeout period is specified in the jps-config.xml file.

To configure the JWT timeout period:

In a text editor, open the $DOMAIN/config/fmwconfig/jps-config.xml file.

2. In the trust.provider.embedded property set, change the value of trust.token.validityPeriod to a value in seconds as in the following example:

<propertySet name="trust.provider.embedded">
    <property name="trust.aliasName" value="xell"/>
    <property name="trust.issuerName" value="www.oracle.com"/>
    <property name="trust.keyStoreName" value="kss://opss/trustservice_ks"/>
    <property name="trust.keystoreType" value="KSS"/>
    <property name="trust.trustStoreName" value="kss://opss/trustservice_ts"/>
    <property name="trust.token.validityPeriod" value="1800"/>

Note:

If the trust.token.validityPeriod property is defined twice in the trust.provider.embedded property set, then delete one definition.

Save the jps-config.xml file.
Restart Oracle Identity Manager Managed Server.

21.5 Endpoints and the Facade Application

Endpoints include the Token endpoint and Refresh Token endpoint. The Facade application fetches a token for the logged in user.

The Token and Refresh Token endpoints are /iam/governance/token/api/v1/tokens.

This section describes the endpoints and the Facade application. It contains the following topics:

21.5.1 Endpoints

The Token and Refresh Token endpoints are /iam/governance/token/api/v1/tokens.

This section describes the Token endpoint and Refresh Token endpoint. It contains the following topics:

21.5.1.1 The Token Endpoint ( /iam/governance/token/api/v1/tokens)

This section describes the token endpoint. It contains the following topics:

21.5.1.1.1 About the Token Endpoint

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

21.5.1.1.2 Token Endpoint Authorization

For authorization, 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.

21.5.1.1.3 Token Request

Token Request (Self)

Token Request (Self) includes the following request method, URL, and headers:

Request method: POST
URL: http://<host>:<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>

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

This section describes the Refresh Token Endpoint. It contains the following topics:

21.5.1.2.1 About the Refresh Token Endpoint

This endpoint is exposed so that the application can refresh its existing token by providing the old token before it expires. This endpoint validates the existing token and then reissues a token if the existing token is still valid. This endpoint is protected by JWT OWSM policy.

21.5.1.2.2 Refresh Token End Point Configuration

Table 21-1lists the Refresh Token endpoint configuration.

Table 21-1 Refresh Token Endpoint Configuration

Use Case	Availability	Description
Web browser with existing Oracle Identity Manager UI login session (non-SSO)	No	The application fetches the token for the logged-in user by using the Façade application. Because the user can log out from Oracle Identity Manager any time, the refresh endpoint is not available in this scenario. If the user is still logged in to Oracle Identity Manager when the user token expires, then the application can get a new token by using the Façade application.
Web browser with existing Oracle Identity Manager UI login session (SSO)	No	The application fetches the token for the logged-in user by using the Façade application. Because the user can log out from SSO any time, the refresh endpoint is not available in this scenario. If the user is still logged in to SSO when the user token expires, then the application can get a new token by using the Façade application.
Web browser via portal with Oracle Identity Manager as the Identity Store	Yes	The application fetches the token directly by accessing the /tokens endpoint and providing the user name and password. If the token is about to expire, then the application accesses the /tokens endpoint by providing the existing token and receives a new token.
Web browser via portal with an external authentication provider	Yes	The application fetches the token for a user who is authenticated by an external authentication provider. If the token is about to expire, then the application accesses the /tokens endpoint by providing the existing token and receives a new token.

21.5.1.2.3 Refresh Token Request

The Refresh Token Request includes the following request method, URL, and headers:

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

21.5.2 The Facade Application

The Facade application is fetches a token for the logged-in user based on the existing user session. Users who are logged in to an OIM/SSO application and moved to an HTML/JS application can use the façade application to get the token for the logged-in user.

Table 21-2 shows the usability of the Facade application.

Table 21-2 Facade Application Usability

Use Case	Required
Web browser with existing Oracle Identity Manager UI login session (non-SSO)	Yes
Web browser with existing Oracle Identity Manager UI login session (SSO)	Yes
Web browser via portal with Oracle Identity Manager as the identity store	No
Web browser via portal with an external authentication provider	No

A user can use the FacadeWebApp REST API to fetch a JWT token by using the following URI:

/FacadeWebApp/GetToken GET: This retrieves the JWT token for the user. See REST API for FacadeWebApp Token Service.

21.6 CSRF and CORS Protection

Custom request headers are used to protect SCIM resources from Cross-Site Request Forgery (CSRF) attacks. Cross-origin HTTP requests are restricted by using the Cross-Origin Resource Sharing (CORS) mechanism.

See Securing SCIM Resources for detailed information about CSRF and CORS protection.