REST APIs for Oracle Identity Manager (OIM) 11g R2 PS3 were released recently. The availability of REST APIs enables a variety of newer integrations with the product in addition to already available mechanisms using Java APIs.
In this article, we discuss various ways of accessing these REST APIs in a secure manner. Please note that irrespective of how users’ authenticate to OIM, what data can they access and what actions can they perform depends only on OIM’s authorization model and Admin Role grants.
Readers are expected to be familiar with common authentication technologies like HTTP Basic, SAML 2.0 and JWT. The focus of this article is more on describing the integration guidelines – mostly on the OIM side rather than detailed configuration steps, although some important configuration steps are indeed described in detail. References are provided at appropriate places for more information.
The Unix/Linux cURL command is used to demonstrate the authentication results.
Oracle Web Services Manager (OWSM) Policies
OIM REST APIs are secured using OWSM security policies. Out-of-the-box (OOTB), OIM REST APIs are protected by “oracle/multi_token_noauth_over_ssl_rest_service_policy” OWSM policy. This policy expects REST clients to connect to OIM Server over SSL/TLS. However, It is also possible to access the APIs over non-SSL channels (for example – if SSL is off-loaded/terminated at the load balancer or in the case of development like environments) – Please refer to My Oracle Support (MOS) Doc ID 2204171.1 for detailed steps on how to perform this configuration.
This policy combines (by the “OR” operator) the functionality of two OWSM predefined policies –“oracle/multi_token_over_ssl_rest_service_policy” and “oracle/no_authentication_service_policy”. OWSM policy “oracle/multi_token_over_ssl_rest_service_policy” supports multiple authentication mechanisms – HTTP Basic, SAML 2.0 bearer tokens, JWT tokens and SPNEGO. REST API clients can authenticate themselves using any one of these mechanisms.
User Authentication in Common OIM Deployment Models
Enterprises typically deploy OIM in the following two configurations. These deployment profiles directly influence how users authenticate to OIM:
Stand Alone OIM: Users are authenticated by the Weblogic container hosting the OIM application. Users use their credentials stored in OIM datastore (OIM DB) or some other (like corporate LDAP directory server or Microsoft AD) credentials for authentication.
OIM protected by a SSO provider (for example – Oracle Access Manager (OAM)): In this case users are authenticated by their SSO provider and asserted by the Weblogic container hosting OIM.
REST API authentication for these OIM deployment profiles are described below:
Stand Alone OIM: HTTP Basic authentication
Users can use their OIM credentials (user login id/password) in the HTTP call (aka HTTP Basic Authentication) as shown in the following sample cURL command to retrieve self profile information. This mode is convenient for quickly testing REST API calls from command line during development.
$ curl -ssl -k -X GET --user JSMITH:Abcd1234 'https://localhost:14001/iam/governance/selfservice/api/v1/users?q=User::Login eq JSMITH'
Please note that “::” is used to specify the whitespace in the name of attribute – “User Login” is specified as “User::Login”.
Stand alone OIM: JWT token authentication
OIG REST Services provides a “tokens” end point, which can be used to get a JWT token issued by providing users’ credentials. Once issued, this token can be used in any further REST API calls rather than providing a user login id /password each time. This approach of working with tokens should be preferred over the user login id/password approach specified above. Tokens are issued for a fixed period and can be renewed before they expire.
The tokens end point is located at: https://<Host Name>:<Port Number>/iam/governance/token/api/v1/tokens
Here are the steps to get the self-profile information using a JWT token for authentication:
Get a token from tokens end point: Sample cURL command:
$ curl -ssl -k -X POST -u JSMITH:Abcd1234 https://localhost:14001/iam/governance/token/api/v1/tokens
Use the token to make REST API calls: Once a token is issued, it can be used to make REST API calls without any need to specify the user id/password until the token expires. Following is equivalent REST API call to retrieve self-profile information using the obtained token:
$ curl -ssl -k -X GET --header 'Authorization: Bearer <Token from the step above>' 'https://localhost:14001/iam/governance/selfservice/api/v1/users?q=User::Login eq JSMITH'
Please note that the token is a Bearer token.
Renew Access Tokens: Tokens could be renewed by providing the current access token and executing a PUT request against the token end point provided that the current access token is still valid. Here is an example:
$ curl -ssl -k -X PUT --header 'Authorization: Bearer <Token from the step above>' https://localhost:14001/iam/governance/token/api/v1/tokens
OIM protected by a SSO solution (OAM): Authentication using SAML 2.0 token
In cases where OIM is protected by a SSO solution (for example – OAM), authentication to OIM REST APIs can be done using a SAML 2.0 token generated by the SSO provider upon user authentication
Please refer to the following blog post by my colleague Simon Kissane describing how to authenticate using a SAML token generated by OAM:
OIM protected by a SSO solution (OAM): Authentication using JWT token:
In cases where OIM is protected by a SSO solution (for example – OAM), authentication to OIM REST APIs can also be done using a JWT token generated by the SSO provider upon user authentication.
Although the steps required for authenticating to OIM REST service with a JWT token are similar in principle to that of the SAML token use case, I will describe the configuration steps required on the OIM (/OWSM) side for this use-case in some depth. In this example a signed but unencrypted JWT token is used. Following are the high-level steps needed to perform this integration:
- Generation of signed JWT tokens
- Configuring OWSM to trust the JWT token issuer
- Importing the public certificate of the JWT token issuer (to verify the signature with which the JWT token is signed) in OWSM truststore.
Let’s discuss these steps in more detail.
Generation of signed JWT tokens:
In most cases this step will be performed by the SSO provider after authenticating the user. Please make sure that in addition to the other standard headers, one of the following two headers has a valid value:
- x5t – SHA-1 thumbprint of the X509 certificate
- kid – Alias of the certificate in OWSM’s keystore that will be used to verify the signature that signed the JWT token. Specifying the kid header will require some pre-arrangement between the token issuer (SSO provider) and token verifier (OWSM).
Configuring OWSM to trust the JWT token issuer:
I configured my OWSM instance to accept JWT tokens issued by “ateam.oracle.com” using the following steps:
- Start $OIM_ORACLE_HOME/common/bin/wlst.sh
- Enter the command connect(), then enter your Weblogic admin credentials (e.g. Weblogic user and associated password), and your OIM domain AdminServer URL (e.g. t3://OIMHOST1:7001).
- Enter the command setWSMTokenIssuerTrust(“dns.jwt”,”ateam.oracle.com”,)
(Note this command is documented in the OWSM 188.8.131.52 Admin Guide, chapter 14, section – Configuring an Issuer and its DN List Using WLST.). You will need to wait approximately 10 minutes due to caching in OWSM before this setting takes effect. Alternatively, you can restart your OIM managed server(s).
Import the public certificate in OWSM truststore:
The public certificate corresponding to the private key that is used to sign the JWT token needs to be imported in OWSM’s trust store in order for OWSM to be able to perform signature validation. It can be done with the Java keytool command. For example –
<JDK_HOME>/bin/keytool -importcert -keystore <DOMAIN_HOME>/config/fmwconfig/default-keystore.jks -storetype JKS -storepass <Password> -file <Certificate File Path> -alias <Alias Name> -trustcacerts
A couple of data points to note in the above command line –
- OWSM’s default keystore is located at <DOMAIN_HOME>/config/fmwconfig/default-keystore.jks.
- Password for this default keystore could be obtained from EM by navigating through the following sequence: Weblogic Domain –> <Domain Name> –> System MBean Browser (available from the “Weblogic Domain” drop down in the main panel) –> Application Defined MBeans –> com.oracle.jps –> Server: <OIM Server Name> –> JPSCredentialStore –> JPSCredentialStore (MBean) –> Operations tab –> Select “getPortableCredential”. Use value “oracle.wsm.security” for p1 and “keystore-csf-key” for p2 and invoke the operation. Password is returned in the result data.
Here are the results of an example execution on my instance:
I used a third party library to create and sign the JWT token. The subject of the token is set to user “jsmith” and the issuer is “ateam.oracle.com” as shown in the decode of the JWT token body:
Using this token authenticates to OIM (/OWSM) as user “jsmith” and we can get the self profile details for this user using the following cURL sample, similar to what we did in the Stand-alone OIM – JWT token use-case :
$ curl -ssl -k -X GET --header 'Authorization: Bearer <Token from the step 'Generation of signed JWT tokens'>' 'https://localhost:14001/iam/governance/selfservice/api/v1/users?q=User::Login eq JSMITH'
[Acknowledgements – My colleague Simon Kissane contributed to this post. Many Thanks Simon!]
All site content is the property of Oracle Corp. Redistribution not allowed without written permission