22 Using the JSON Web Token Service
Using the JSON Web Token (JWT) service simplifies the use of Oracle Identity Governance SCIM and REST services.
This chapter describes how to use the JWT service for Oracle Identity Governance SCIM and REST services. It contains the following topics:
22.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.
22.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.
-
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
.
22.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.
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.
22.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:
22.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.
22.4.2 JSON Web Token (JWT)
The JSON Web Token (JWT) is defined in RFC 7519.
{"exp":1448420525,"sub":"xelsysadm","iss":"www.oracle.com","prn":"xelsysadm","iat":1448418725}
{"alg":"RS256","typ":"JWT","x5t":"8KTfKAncWGbLsNOlLZRQ77qSE74","kid":"xell"}
{ "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
.
22.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.
22.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.
22.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:
22.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:
22.5.1.1 The Token Endpoint ( /iam/governance/token/api/v1/tokens)
This section describes the token endpoint. It contains the following topics:
22.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.
22.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.
22.5.1.1.3 Token Request
Token Request (Self)
Token Request (Self) includes the following request method, URL, and headers:
-
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 The Refresh Token Endpoint (/iam/governance/token/api/v1/tokens)
This section describes the Refresh Token Endpoint. It contains the following topics:
22.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.
22.5.1.2.2 Refresh Token End Point Configuration
Table 22-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. |
22.5.1.2.3 Refresh Token Request
The Refresh Token Request includes the following request method, URL, and headers:
-
Request method: POST
-
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>
-
22.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 22-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.
22.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.