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:
This section describes how to use the JWT service for Oracle Identity Manager SCIM and REST services. It contains the following sections:
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.
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
.
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.
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.
This section describes the JWT-based OIM identity provider for SCIM and REST authentication. It contains the following sections:
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());
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
.
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.
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.
This section describes the end points and the application details. It contains the following section:
This section describes the Token end point and Refresh Token end point. It contains the following sections:
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.
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.
This section describes the following token end point scenario:
Token-For-Self: Web browser via portal with Oracle Identity Manager as the Identity Store
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>
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 |
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>