14 Using the OAuth Service API

This chapter describes the Oracle Access Management OAuth Service API. This chapter includes the following topics:

Notes About Using cURL

This chapter uses cURL to demonstrate the REST calls that the OAuth client sends to the Mobile and Social OAuth server. cURL is free software that you can download from the cURL website at http://curl.haxx.se/

Using cURL to send REST calls to the server can help you better understand how the client interacts with the server. It can also be a helpful troubleshooting tool.

Note:

cURL commands that contain single quotes ( ' ) will fail on Windows. When possible, use double quotes ( " ) in place of single quotes.

If a command requires both single quotes and double quotes, escape the double quotes with a backslash (for example: \" ) and replace the single quotes with double quotes.

Note:

In this guide, line breaks in cURL commands and server responses are for display purposes only.

Standard Three-Legged OAuth Flows

This section documents the REST calls for the 3-legged OAuth flows. For more information, see "Understanding OAuth 3-Legged Authorization" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

Sample Request

The following sample has two parts: the front-channel flow, which takes place between the OAuth server and the resource owner (or end user), and the back-channel flow, which takes place between the OAuth server and the client application.

Part One: Front-Channel Request

In the following flow, the client application redirects the user (the resource owner) to the OAuth server's authorization endpoint using a browser. The user needs to authenticate with the OAuth server and, optionally, authorize access to the requested resources (provide consent). Once the user interaction completes successfully, the OAuth server issues an authorization code back to the client application.

The client application then uses the authorization code to request a resource access token, which is a back-channel request.

curl - i
--request GET "https://host:port/ms_oauth/oauth2/endpoints/oauthservice/authorize?
response_type=code
&client_id=54321id
&redirect_uri=http://client.example.com/return
&scope=user_read&state=xyz"

Table 14-1 Request Parameters

Name Description Required

response_type

Value must be code for this flow.

Required

client_id

A client identifier given by the authorization server.

The authorization server validates the client_id value with the configuration (the client registry). If the value is invalid, an error response is sent to the user-agent.

Required

redirect_uri

The client app's redirect URI authorization code. If not sent, then the configuration/client registry is checked to see if a redirect_uri value is defined. Else, an error response is sent to the user-agent.

Optional

scope

Use space-separated values. Define scope values in the configuration/scope registry. If no scope is sent, or if an invalid scope is specified, an error response is sent to the client app's redirect_uri.

Required

state

An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used to prevent cross-site forgery requests.

Recommended


Sample Authorization Code Response

https: //client.example.com/return?code=eyJhbG...rWWk8hbs_o6uY&state=xyz

If the resource owner grants the access request, the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the application/x-www-form-urlencoded format.

Table 14-2 Response Parameters

Name Description

code

Includes the following:

  • Expiry (15 minutes by default. To change this value, open the OAuth Service Profile Configuration page and update the Expires setting under Token Settings.)

  • Client_id

  • Redirect_uri

state

Same value specified in the authorization request. Only included if it was specified in the authorization request.


Error Response

If validation errors are found, a JSON response containing error codes and descriptions is sent. Following are some error codes and their descriptions:

invalid_client - client identifier invalid

access_denied - end-user denied authorization

invalid_redirect_uri - redirect_uri mismatch with client app

invalid_scope - requested scope is invalid, unknown, or malformed

server_error - runtime processing error

Error Response Sample

{”error_code”:”invalid_client”, ”error_description”:”client identifier invalid”}

Part 2: Back-Channel Request

This flow is between the OAuth server (the authorization server) and the client application. The sample shows how to exchange the authorization code for an OAuth Access Token.

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://hostname:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
    redirect_uri=http%3A%2F%2Fclient.example.com:17001%2Freturn
    &grant_type=authorization_code
    &code=eyJhbG...rWWk8hbs_o6uY
   '

The grant_type parameter value must be authorization_code, and the code parameter value must be the authorization code generated by the authorization endpoint. You must send the redirect_uri token if the redirect_uri parameter was included in the authorization request. The value must be the same.

Sample Response

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

Standard Two-Legged OAuth Flows

This section provides sample REST requests that show how to get a resource access token. When no resource is sent in the request, the resulting token can be used as an Identity Token. For more information, see "Understanding OAuth 2-Legged Authorization" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management. This section includes the following examples:

Sample Response

The following response is typical for the requests documented in this section.

Note:

The refresh_token element is included in the server response if a requested scope is designated as an offline scope.The refresh_token element is not sent if none of the scopes is offline.
 HTTP/1.1 200 OK
 
 Cache-Control: no-cache, no-store, must-revalidate
 
 Date: Wed, 04 Dec 2013 21:52:03 GMT
 
 Pragma: no-cache
 
 Transfer-Encoding: chunked
 
 Content-Type: application/json
 
 X-ORACLE-DMS-ECID: 09edd9b26949554d:-1f8be51:142bf50a0dc:-8000-0000000000001b27
 
 X-Powered-By: Servlet/2.5 JSP/2.1
 
 {
   "expires_in":3600,
   "token_type":"Bearer",
   "access_token":"<access token value>", 
   "refresh_token":"<refresh token value">
 }

Using Client Credentials

The following sample shows how to use client credentials to get an access token.

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://hostname:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
    grant_type=client_credentials
    &scope=scope1%20scope2
   '

Using the Resource Owner Credentials

The following sample shows a resource owner request that includes user ID and password credentials, as well as a client ID and secret in an HTTP Basic header.

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://hostname:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=password
    &username=userxyz
    &password=pwd123xyz
    &scope=scope1%20scope2'

Using a Refresh Token

The following sample shows using a refresh token with clientid:clientsecret in the basic authorization header.

curl -i 
-H 'Authorization: Basic dGVzdDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://hostname:port/ms_oauth/oauth2/endpoints/oauthservice/tokens -d 'grant_type=refresh_token
   &refresh_token=<refresh-token-value>'

This next example shows using the client assertion as a client credential.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=refresh_token
   &refresh_token=<refresh-token-value>
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion=<client-assertion-value>'

Using a SAML Client Assertion

The following sample shows a client credentials request that uses a SAML client assertion generated by a third party.

curl -i
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'client_id=54321id
    &grant_type=client_credentials
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Asaml2-bearer
    &client_assertion=<SAML client assertion value>
    &scope=scope1%20scope2'

Using a JWT Client Assertion

The following sample shows an authorization code request that uses a JWT client assertion generated by the IDM OAuth Server or a third party.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'client_id=54321id
   &grant_type=client_credentials
   &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
   &client_assertion=<JWT client assertion value>
   &scope=scope1%20scope2'

Using User ID/Password Credentials and ClientID+Secret in an HTTP Basic Header

The following sample shows a resource owner request that uses user ID and password credentials, plus a ClientID and secret in the HTTP Basic header.

curl -i 
-H 'Authorization: Basic <base64encoded(clientID:Secret)>' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
    grant_type=password
    &username=user123
    &password=password123
  '

Using User ID/Password Credentials and a JWT Client Assertion

The following sample shows a resource owner request that uses user ID and password credentials, and a JWT client assertion generated by a third party.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=password
    &username=userxyz
    &password=pwd123xyz
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
    &client_assertion=<JWT client assertion value>
    &scope=scope1%20scope2'

Using UserID/Password Credentials and a SAML Client Assertion

The following sample shows an authorization code request that uses user ID and password credentials, and a SAML client assertion generated by a third party.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=password
    &username=userAbc123
    &password=passwordAbc123
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Asaml2-bearer
    &client_assertion=<SAML client assertion value>
    &scope=scope1%20scope2'

Using a SAML User Assertion Credential and ClientID+Secret in an HTTP Basic Header

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer
    &assertion=<SAML user assertion value>'
    &scope=scope1%20scope2

Using a SAML User Assertion Credential and a SAML Client Assertion

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Asaml2-bearer
    &client_assertion=<SAML client assertion value>
    &assertion=<SAML user assertion value> 
    &scope=scope1%20scope2'

Using a SAML User Assertion Credential and a JWT Client Assertion

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
    &client_assertion=<JWT client assertion value>
    &assertion=<SAML user assertion value>
    &scope=scope1%20scope2'

Using a JWT User Assertion Credential and ClientID+Secret in an HTTP Basic Header

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
    &assertion=<JWT user assertion value>
    &scope=scope1%20scope2'

Using a JWT User Assertion Credential and a SAML Client Assertion

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Asaml2-bearer
    &client_assertion=<SAML client assertion value>
    &assertion=<JWT user assertion value>
    &scope=scope1%20scope2'

Using a JWT User Assertion Credential and a JWT Client Assertion

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
    &client_assertion=<JWT client assertion value>
    &assertion=<JWT user assertion value>
    &scope=scope1%20scope2'

Identity Token Acquisition

This section demonstrates how to get an access token (that is, an identity token for client and user) from the OAuth server. It includes the following samples:

Getting a Client Identity Token

This section shows three ways to get a client identity token.

Using Client Credentials

This sample includes the ClientID+Secret in the HTTP Basic Auth header.

curl - i 
- H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
- H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
--request POST http: //host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=client_credentials' 

Sample Response

{
  "oracle_client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "expires_in": 604800,
  "token_type": "Bearer",
  "oracle_tk_context": "client_assertion",
  "access_token": "access token value" > ,
  "refresh_token": "<refresh token value>"
}

Using a Third-Party Generated SAML Client Assertion

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   client_id=54321id
   &grant_type=client_credentials
   &client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Asaml2-bearer
   &client_assertion=<SAML client assertion value>
   '

Refer to the sample response in the first example.

Using a Third-Party Generated JWT Client Assertion

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   client_id=54321id
   &grant_type=client_credentials
   &client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
   &client_assertion=<JWT client assertion value>
   '

Refer to the sample response in the first example.

Getting a User Identity Token

The samples in this section demonstrate how to get a user identity token, also referred to as an access token or user assertion. There are three categories.

Sample Response

All of the requests receive a response similar to the following:

{
  "expires_in": 28800,
  "token_type": "Bearer",
  "oracle_tk_context": "user_assertion",
  "oracle_grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "access_token": "<access token value>"
}

Getting a User Identity Token With a User ID and Password and Varying Client Credentials

This category has three samples.

Using UserID/Password Credentials and a ClientID+Secret in the HTTP Basic Header
curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   grant_type=password
   &username=sampleuser
   &password=samplepassword
   '

Using UserID/Password Credentials and a Third-Party JWT Client Assertion
curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   grant_type=password
   &username=sampleuser
   &password=samplepassword
   &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
   &client_assertion=<JWT client assertion value>
   '
Using UserID/Password Credentials and a Third-Party SAML Client Assertion
curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   grant_type=password
   &username=sampleuser
   &password=samplepassword
   &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Asaml2-bearer
   &client_assertion=<SAML client assertion value>'


Getting a User Identity Token With a SAML User Assertion Credential and Varying Client Credentials

This category has three samples.

Using a Third-Party SAML User Assertion Credential and a ClientID+Secret in the HTTP Basic Header
curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer
   &assertion=<SAML user assertion value>'
Using a Third-Party SAML User Assertion Credential and a SAML Client Assertion
curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer
   &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Asaml2-bearer
   &client_assertion=<SAML client assertion value>
   &assertion=<SAML user assertion value>'

Using a Third-Party SAML User Assertion Credential and a JWT Client Assertion
curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer
   &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
   &client_assertion=<JWT client assertion value>
   &assertion=<SAML user assertion value>'


Getting a User Identity Token With a JWT User Assertion Credential and Varying Client Credentials

This category has three samples.

Using a Third-Party JWT User Assertion Credential and a ClientID+Secret in the HTTP Basic Header
curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
   &assertion=<JWT user assertion value>'
Using a Third-Party JWT User Assertion Credential and a SAML Client Assertion
curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
   &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Asaml2-bearer
   &client_assertion=<SAML client assertion value>
   &assertion=<JWT user assertion value>'
Using a Third-Party JWT User Assertion Credential and a JWT Client Assertion
curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
   grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
   &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
   &client_assertion=<JWT client assertion value>
   &assertion=<JWT user assertion value>'



Validating an Access Token

This section provides sample REST requests that show how to validate a resource access token. It includes the following examples:

Using the Client ID and Secret in an HTTP Basic Header

The following sample shows an access token validation request that includes the client ID and secret in an HTTP Basic header. Note that the assertion value is not a normal string, but a JSON.

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Fresource-access-token%2Fjwt
    &oracle_token_action=validate
    &scope=UserProfile.users.read
    &assertion={"<assertion>":"<assertion-value>"}'

Response

{"successful":true}

Using a Client Assertion

The following sample shows an access token validation request that gets a JWT client assertion using the client credentials grant type, which is used as a credential.

curl -i 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Fresource-access-token%2Fjwt
    &oracle_token_action=validate
    &scope=ConsentManagement.grant
    &assertion=<access token value>
    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer 
    &client_assertion=<JWT client assertion value>'

Response

{"successful":true}

Performing Access Token Introspection

This section provides sample REST requests that show how to query the OAM OAuth authorization server to determine meta-information about an OAuth token. This process, called OAuth introspection, is the same as access token validation but additional claims data is included inside the access token as part of the response.

To request that the server return additional token claims data in its response, include the oracle_token_attrs_retrieval parameter. This parameter takes the following space-separated claims names:

iss aud exp prn jti exp iat oracle.oauth.scope oracle.oauth.client_origin_id
oracle.oauth.user_origin_id oracle.oauth.user_origin_id_type 
oracle.oauth.tk_context oracle.oauth.id_d_id oracle.oauth.svc_p_n

This section includes the following examples:

Using the Client ID and Secret in the HTTP Basic Header

The following token introspection sample shows the first access token validation request shown previously in the Validating an Access Token section, but with the addition of the oracle_token_attrs_retrieval parameter.

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Fresource-access-token%2Fjwt
    &oracle_token_action=validate
    &scope=UserProfile.users.read
    &oracle_token_attrs_retrieval=iss%20aud%20exp%20prn%20jti%20exp%20iat
%20oracle.oauth.scope%20oracle.oauth.client_origin_id
%20oracle.oauth.user_origin_id%20oracle.oauth.user_origin_id_type
%20oracle.oauth.tk_context%20oracle.oauth.id_d_id%20oracle.oauth.svc_p_n
    &assertion=<access token value>'

Response

{"successful":true,
 "oracle_token_attrs_retrieval":
 {"oracle.oauth.tk_context":"resource_access_tk",
  "exp":1386276668000,
  "iss":"www.oracle.example.com",
  "prn":"54321id",
  "oracle.oauth.client_origin_id":"54321id",
  "oracle.oauth.scope":"ConsentManagement.grant",
  "jti":"0fb4eef6-44ce-46ac-9230-7a335c05bf0f",
  "oracle.oauth.svc_p_n":"OAuthServiceProfile",
  "iat":1386273068000,
  "oracle.oauth.id_d_id":"12345678-1234-1234-1234-123456789012"
 }
}

Using a Client Assertion

The following token introspection sample shows the second access token validation request shown previously in the Validating an Access Token section, but with the addition of the oracle_token_attrs_retrieval parameter.

curl -i 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Fresource-access-token%2Fjwt
    &oracle_token_action=validate
    &scope=ConsentManagement.grant
    &oracle_token_attrs_retrieval=iss%20aud%20exp%20prn%20jti%20exp%20iat
%20oracle.oauth.scope%20oracle.oauth.client_origin_id
%20oracle.oauth.user_origin_id%20oracle.oauth.user_origin_id_type
%20oracle.oauth.tk_context%20oracle.oauth.id_d_id%20oracle.oauth.svc_p_n
    &assertion=<access token value>
    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer 
    &client_assertion=<JWT client assertion value>'

Response

{"successful":true,
 "oracle_token_attrs_retrieval":
 {"oracle.oauth.tk_context":"resource_access_tk",
  "exp":1386276668000,
  "iss":"www.oracle.example.com",
  "prn":"54321id",
  "oracle.oauth.client_origin_id":"54321id",
  "oracle.oauth.scope":"ConsentManagement.grant",
  "jti":"0fb4eef6-44ce-46ac-9230-7a335c05bf0f",
  "oracle.oauth.svc_p_n":"OAuthServiceProfile",
  "iat":1386273068000,
  "oracle.oauth.id_d_id":"12345678-1234-1234-1234-123456789012"
 }
}

Revoking an Access Token

This section provides sample REST requests that show how to revoke a resource access token. It includes the following examples:

Using the Client ID and Secret in the HTTP Basic Header

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Fresource-access-token%2Fjwt
    &oracle_token_action=delete
    &assertion=<access token value>'

Response

{"successful":true}

Using a Client Assertion

curl -i 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Fresource-access-token%2Fjwt
    &oracle_token_action=delete
    &assertion=<access token value>
    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
    &client_assertion=<JWT client assertion value>'

Response

{"successful":true}

OAuth User Profile Service REST Interface

The following User Profile Service REST commands are documented in this section.

Read My Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.me.read.

curl -i 
--request GET 
"http://host:port/ms_oauth/resources/userprofile/me" 
-H 'Authorization:<OAUTH ACCESS TOKEN>'

Response

{
  "uid": "weblogic",
  "description": "This user is the default administrator.",
  "lastname": "Doe",
  "commonname": "John",
  "uri": "\/ms_oauth\/resources\/userprofile\/me\/weblogic"
}

Update My Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.me.write.

curl -H 
"Content-Type: application/json" 
--request PUT "http://host:port/ms_oauth/resources/userprofile/me"
-H 'Authorization:<OAUTH ACCESS TOKEN>' 
-d '{     "description": "user2description"    }'

Response

{
  "uid": "weblogic",
  "description": "user2description",
  "lastname": "Doe",
  "commonname": "John",
  "uri": "\/ms_oauth\/resources\/userprofile\/me\/weblogic"
}

Create a User Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.users.write.

curl -H 
"Content-Type: application/json" 
--request POST
http://host:port/ms_oauth/resources/userprofile/users 
-H 'Authorization:<OAUTH ACCESS TOKEN>' 
-d '{
     "uid": "John",
     "description": "test user",
     "lastname": "Anderson",
     "commonname": "John Anderson",
     "firstname": "John"
    }'

Response

{
  "uid": "John",
  "guid": "FE1D7BD0590111E1BFDCF77FB8E715D5",
  "description": "test user",
  "name": "John",
  "lastname": "Anderson",
  "commonname": "John Anderson",
  "loginid": "John",
  "firstname": "John",
  "uniquename": "FE1D7BD0590111E1BFDCF77FB8E715D5",
  "uri": "\/ms_oauth\/resources\/userprofile\/people\/John"
}

Read a User Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.users.read.

curl -i 
--request GET 
-H 'Authorization:<OAUTH ACCESS TOKEN>'
http://host:port/ms_oauth/resources/userprofile/users/John

Response

{
  "uid": "John",
  "guid": "FE1D7BD0590111E1BFDCF77FB8E715D5",
  "description": "test user",
  "name": "John",
  "lastname": "Anderson",
  "commonname": "John Anderson",
  "loginid": "John",
  "firstname": "John",
  "uniquename": "FE1D7BD0590111E1BFDCF77FB8E715D5",
  "uri": "\/ms_oauth\/resources\/userprofile\/people\/John"
}

Update a User Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.users.write.

curl -H "Content-Type: application/json" 
--request PUT
http://host:port/ms_oauth/resources/userprofile/users/John 
-H 'Authorization:<OAUTH ACCESS TOKEN>' 
-d '{
     "description":"test user1"
    }'

Response

{
  "uid": "John",
  "guid": "FE1D7BD0590111E1BFDCF77FB8E715D5",
  "description": "test user1",
  "name": "John",
  "lastname": "Anderson",
  "commonname": "John Anderson",
  "loginid": "John",
  "firstname": "John",
  "uniquename": "FE1D7BD0590111E1BFDCF77FB8E715D5",
  "uri": "\/ms_oauth\/resources\/userprofile\/people\/John"
}

Delete a User Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.users.write.

curl -i 
--request DELETE 
-H 'Authorization:<OAUTH ACCESS TOKEN>' 
http://host:port/ms_oauth/resources/userprofile/users/John

Response

No Response.

Create a Group Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.users.write.

curl -H "Content-Type: application/json" 
--request POSThttp://host:port/ms_oauth/resources/userprofile/groups 
-H 'Authorization:<OAUTH ACCESS TOKEN>' 
-d '{
     "description":"group1 testing",
     "commonname":"group1"
    }'

Response

{
  "guid": "2259C6C0592011E1BFDCF77FB8E715D5",
  "description": "group1 testing",
  "name": "group1",
  "commonname": "group1",
  "uniquename": "2259C6C0592011E1BFDCF77FB8E715D5",
  "uri": "\/ms_oauth\/resources\/userprofile\/groups\/group1"
}

Read a Group Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.groups.read.

curl -i 
--request GET "http://host:port/ms_oauth/resources/userprofile/groups/group1" 
-H 'Authorization:<OAUTH ACCESS TOKEN>'

Response

{
  "guid": "2259C6C0592011E1BFDCF77FB8E715D5",
  "description": "group1 testing",
  "name": "group1",
  "commonname": "group1",
  "uniquename": "2259C6C0592011E1BFDCF77FB8E715D5",
  "uri": "\/ms_oauth\/resources\/userprofile\/groups\/group1"
}

Update a Group Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.groups.write.

curl -H "Content-Type: application/json" 
--request PUT http://host:port/ms_oauth/resources/userprofile/groups/group1 
-H 'Authorization:<OAUTH ACCESS TOKEN>' 
-d '{
     "description":"group11 testing"
    }'

Response

{
  "guid": "2259C6C0592011E1BFDCF77FB8E715D5",
  "description": "group11 testing",
  "name": "group1",
  "commonname": "group1",
  "uniquename": "2259C6C0592011E1BFDCF77FB8E715D5",
  "uri": "\/ms_oauth\/resources\/userprofile\/groups\/group1"
}

Delete a Group Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.groups.write.

curl -i 
--request DELETE "http://host:port/ms_oauth/resources/userprofile/groups/group1" 
-H 'Authorization:<OAUTH ACCESS TOKEN>'

Response

Delete a User Profile

This resource server URI is protected by an OAuth Access Token. To complete this action using the default configuration, the OAuth Access Token requires a scope of userProfile.users.write.

curl -i 
--request DELETE 
-H 'Authorization:<OAUTH ACCESS TOKEN>' 
http://host:port/ms_oauth/resources/userprofile/users/John

Response

No Response.

OAuth Consent Management REST Interfaces

Use this interface to customize the consent experience by rendering a custom user interface and driving the user consent process. This interface retrieves the client's consent status for all users and scopes with the POST/consentmanagement/retrieve grant. Using this interface you can enable the client to show a user all of the scopes they have previously granted.

To enable the UserConsent service, see "Configuring OAuth Consent Management Services" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management. Configure the permissions in the Scopes section as needed.

The following topics are covered in this section:

Get an Access Token with Client Credentials and the Scope

The following sample shows how to get an access token using the client_credentials grant type.

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
    grant_type=client_credentials
   &scope=ConsentManagement.retrieve 
          ConsentManagement.grant 
          ConsentManagement.revoke'

Response

{
  "expires_in": 3600,
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSyfecz3p...nYlReMjATbLs"
}

Access the Consent Management Resource Server

This section includes three sample requests. The following response is typical for all three requests.

Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Date: Fri, 16 Aug 2013 18:26:25 GMT
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
X-ORACLE-DMS-ECID: 316690b8df2db0a3:-794ed83e:140885d3651:-8000-0000000000000028
X-Powered-By: Servlet/2.5 JSP/2.1
X-OAUTH-REST-VERSION: v1

Requests

The following sample demonstrates sending a request to the retrieve endpoint.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/resources/consentmanagement/retrieve 
-d '
    scope=samplePhotoServer.photo.read
   &client_id=54321id
   &oracle_user_id=weblogic
   &lang=en
   '
-H 'Authorization: eyJhbGciOiJSUzUxM...eZJpL08yCI'

The following sample sends a request to the grant endpoint.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/resources/consentmanagement/grant 
-d '
     scope=samplePhotoServer.photo.read
    &client_id=54321id
    &oracle_user_id=weblogic
    &lang=en
   ' 
-H 'Authorization: eyJhbGciOiJSUzUxM...3OxH7jIRqGL-6w'

The final sample demonstrates a request sent to the revoke endpoint.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/resources/consentmanagement/revoke 
-d '
    scope=samplePhotoServer.photo.read
   &client_id=54321id
   &oracle_user_id=weblogic
   &lang=en
   ' 
-H 'Authorization: eyJhbGciOiJSUzUxM...3OxH7jIRqGL-6w'

Grant the Client Permission to Access the User's UserProfile Resource

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/resources/consentmanagement/grant 
-d '
     scope=UserProfile.me.read
    &client_id=54321id
    &oracle_user_id=weblogic
    &lang=en
   ' 
-H 'Authorization: eyJhbGciOiJSUzUxM...3OxH7jIRqGL-6w'

Response

HTTP/1.1 200 OK

Get the Access Token for the User's UserProfile Resource

curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d '
     grant_type=password
    &username=weblogic
    &password=password123
    &scope=UserProfile.me.read'

Response

{
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "eyJhbGciOiJSUzUxM...t7ihyNjqbb6Q9bCwE",
  "access_token": "eyJhbGciOiJSUzUxM...MIXI0ztb6NfOBMb4A"
}

Access the User's UserProfile Resource with the Access Token

The following sample demonstrates an unauthorized request and the response.

curl -i 
--request GET "http://host:port/ms_oauth/resources/userprofile/me" -H 'Authorization: eyJhbGciOiJSUzUxM...MIXI0ztb6NfOBMb4A'

Response

HTTP/1.1 401 Unauthorized
Date: Fri, 16 Aug 2013 18:47:44 GMT
Transfer-Encoding: chunked
Content-Type: application/json
X-ORACLE-DMS-ECID: 316690b8df2db0a3:-794ed83e:140885d3651:-8000-000000000000005e
X-Powered-By: Servlet/2.5 JSP/2.1

{  "message":
 "oracle.security.idaas.oauth.resourceserver.jaxrs.userprofile.Me.getMyProfile: resource uri is not protected",
  "oicErrorCode": "IDAAS-20027 :
 oracle.security.idaas.rest.jaxrs.OICExceptionMapper : [ No error code is
 available from the underlying exception ]"
}

OAuth Mobile Client Two-Legged Flows

This section documents the REST calls for 2-legged mobile client flows. For more information, see "Understanding Mobile OAuth Authorization" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

Note:

All attribute names and values are case-sensitive.

The following topics are covered in this section:

Get Application Profile

curl -i 
--request GET 'http://host:port/ms_oauth/oauth2/endpoints
/oauthservice/appprofiles/MobileApp1?device_os=iPhone%20OS&os_ver=7.000000'

HTTP Response Without Jail-Breaking Detection Policies

{
 "client_id":"MobileApp1",
 "mobileAppConfig":{
  "claimAttributes":[
    "oracle:idm:claims:client:geolocation",
    "oracle:idm:claims:client:imei",
    "oracle:idm:claims:client:jailbroken",
    "oracle:idm:claims:client:locale",
    "oracle:idm:claims:client:networktype",
    "oracle:idm:claims:client:ostype",
    "oracle:idm:claims:client:osversion",
    "oracle:idm:claims:client:phonecarriername",
    "oracle:idm:claims:client:phonenumber",
    "oracle:idm:claims:client:sdkversion",
    "oracle:idm:claims:client:udid",
    "oracle:idm:claims:client:vpnenabled",
    "oracle:idm:claims:client:fingerprint",
    "oracle:idm:claims:client:iosidforvendor",
    "oracle:idm:claims:client:iosidforad"
  ]
 },
 "oauthAuthZService":"/ms_oauth/oauth2/endpoints/oauthservice/authorize",
 "oauthNotificationService":"/ms_oauth/oauth2/endpoints/oauthservice/push",
 "oauthTokenService":"/ms_oauth/oauth2/endpoints/oauthservice/tokens",
 "oracleMobileSecurityLevel":"LOW",
 "userConsentService":["/ms_oauth/resources/consentmanagement"],
 "userProfileService":["/ms_oauth/resources/userprofile"],
 "oracleConsentServiceProtection":"OAM"
}

HTTP Response With Jail-Braking Detection Policies

{
 "client_id":"ACMEStock",
 "jailBreakingDetectionPolicy":
 {
  "autoCheckPeriodInMin":60,
  "detectionLocation":
  [
   {"action":"exists",
    "filePath":"/bin/bash",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/Cydia.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/limera1n.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/greenpois0n.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/blackra1n.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/blacksn0w.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/redsn0w.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/sn0wbreeze.app",
    "success":true
   }
  ],
  "device_os":"iPhone OS",
  "os_ver":"7.000000",
  "policyExpirationInSec":3600
 },
 "mobileAppConfig":
 {
  "claimAttributes":[
   "oracle:idm:claims:client:geolocation",
   "oracle:idm:claims:client:imei",
   "oracle:idm:claims:client:jailbroken",
   "oracle:idm:claims:client:locale",
   "oracle:idm:claims:client:networktype",
   "oracle:idm:claims:client:ostype",
   "oracle:idm:claims:client:osversion",
   "oracle:idm:claims:client:phonecarriername",
   "oracle:idm:claims:client:phonenumber",
   "oracle:idm:claims:client:sdkversion",
   "oracle:idm:claims:client:udid",
   "oracle:idm:claims:client:vpnenabled",
   "oracle:idm:claims:client:fingerprint",
   "oracle:idm:claims:client:iosidforvendor",
   "oracle:idm:claims:client:iosidforad"
  ]
 },
 "oauthAuthZService":"/ms_oauth/oauth2/endpoints/oauthservice/authorize",
 "oauthNotificationService":"/ms_oauth/oauth2/endpoints/oauthservice/push",
 "oauthTokenService":"/ms_oauth/oauth2/endpoints/oauthservice/tokens",
 "oracleMobileSecurityLevel":"LOW",
 "userConsentService":["/ms_oauth/resources/consentmanagement"],
 "userProfileService":["/ms_oauth/resources/userprofile"],
 "oracleConsentServiceProtection":"OAM"
}

Create Mobile Device Client Verification Code

This section shows the REST request for a mobile client verification code for device registration.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2
/endpoints/oauthservice/tokens
-d 'grant_type=client_credentials
    &oracle_device_profile=<Base 64 Encoding Device Profile> 
    &client_id=<MobileApp1>
    &oracle_requested_assertions=oracle-idm:/oauth/assertion-type/client-identity/
mobile-client-pre-authz-code-client'

Response

{
 "expires_in":300,
 "token_type":"Bearer",
 "oracle_tk_context":"pre_azc",
 "access_token":"eyJhbGciOiJg0LzJL...6LnHpAhcZA-EfJU9jQYH4GPINQXXd5_LsQy-D8TW_0Q"
}

Create a Mobile Client Assertion

This request creates a mobile client assertion and a JWT user assertion. The JWT user assertion is stored in the server-side device store.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2
/endpoints/oauthservice/tokens 
-d 'grant_type=password
    &username=userAbc123
    &password=passwordAbc123
    &client_id=<MobileApp1>
    &oracle_pre_authz_code=<Mobile Device Verification Code>
    &oracle_device_profile=<Base 64 Encoding Device Profile> 
    &oracle_requested_assertions=urn:ietf:params:oauth:
client-assertion-type:jwt-bearer'

Response

{
 "expires_in":3600,
 "token_type":"Bearer",
 "access_token":"eyJhbcOiJSzUxMIsInR5cCI6IkpX...OQN5mrZrl5pGyEJOMm4BSLQVVZhLsS5g"
}

Logout

This request cleans the JWT user assertion from the server-side device key chain.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/oammsui/oauthservice/logout 
-d 'client_id=MobileApp1
    &redirect_uri=mobileapp://
    &oracle_device_profile=<Base 64 Encoding Device Profile> 
    &client_assertion=<Mobile Client Assertion>
    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' 

Response

HTTP/1.1 200 OK
 
Date: Mon, 02 Dec 2013 22:55:37 GMT
 
Content-Length: 0
 
Set-Cookie: JSESSIONID=z17tSdPLd7TG11dw7wNtTlJnzGXty3y3B8TqwW1GNvHjmzv6FqGv!535445357; path=/; HttpOnly
 
X-ORACLE-DMS-ECID: 09edd9b26949554d:f4833c6:142b4da1082:-8000-000000000000277f
 
X-Powered-By: Servlet/2.5 JSP/2.1

Login

This request creates a JWT user assertion in the server-side key chain.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2
/endpoints/oauthservice/tokens 
-d 'grant_type=password
    &username=user123
    &password=pwd456xyz
    &client_assertion=<MOBILE CLIENT ASSERTION> 
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type
%3Ajwt-bearer
    &oracle_device_profile=<BASE 64 ENCODING DEVICE PROFILE> 
    &oracle_requested_assertions=oracle-idm%3A%2Foauth%2Fassertion-type
%2Fuser-identity%2Fjwt&oracle_use_server_device_store=true'

Response

{"oracle_token_in_server_device_store":true,
 "expires_in":28800,
 "token_type":"Bearer",
 "oracle_tk_context":"user_assertion",
 "oracle_grant_type":"urn:ietf:params:oauth:grant-type:jwt-bearer",
 "access_token":""}

Create OAM UT and OAM MT using JWT User Assertion (Token Exchange)

This request creates an OAM user token and an OAM master token if the JWT user assertion is valid in the server-side device store.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
–request http://host:port/ms_oauth/oauth2/
endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &user_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Auser-assertion-type
%3Ajwt-bearer
    &client_assertion=<MOBILE CLIENT ASSERTION> 
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type
%3Ajwt-bearer
    &oracle_device_profile=<BASE 64 ENCODING DEVICE PROFILE> 
    &oracle_use_server_device_store=true'

Response

{"oracle_token_in_server_device_store":true,
 "oracle_aux_tokens":
 {"oam_mt":
   {"oracle_tk_context":"oam_mt",
    "oracle_grant_type":"oracle-idm:\/oauth\/grant-type\/oam\/master-token",
    "access_token":"VERSION_4%7EDj10z62v9CQbnuX...Stid6XMhamU%2B"
   }
 },
 "oracle_tk_context":"oam_ut",
 "oracle_grant_type":"oracle-idm:\/oauth\/grant-type\/user-token\/oam",
 "access_token":""
}

Create an OAM Access Token Using an OAM User Token

This request creates an OAM access token and an OAM master token if the OAM user token is valid in the server-side device store. Note that in the following request oracle_oam_application_resource is a WebGate protected resource, and oracle_oam_application_context is a WebGate generated value.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
–request http://host:port/ms_oauth/oauth2/endpoints/
oauthservice/tokens
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &oracle_use_server_device_store=true
    &user_assertion_type=oracle-idm:/oauth/assertion-type/user-identity/oam
    &client_assertion=<MOBILE CLIENT ASSERTION> 
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type
%3Ajwt-bearer
    &oracle_device_profile=<BASE 64 ENCODING DEVICE PROFILE>
    &scope=oracle.security.oauth.oam.resource_access
    &oracle_oam_application_context=<WebGate generated value>
    &oracle_oam_application_resource=http%3A%2F%2Fhost.example.com
%3A12884%2Findex.html'

Response

{
 "oracle_aux_tokens":
   {"oam_ut":
     {"oracle_token_in_server_device_store":true,
      "oracle_tk_context":"oam_ut",
      "oracle_grant_type":"oracle-idm:\/oauth\/grant-type\/user-token\/oam",
      "access_token":""
     }
    },
 "oracle_tk_context":"oam_at",
 "oracle_grant_type":"oracle-idm:\/oauth\/grant-type\/resource-access-token\/oam",
 "access_token":"3F62m7EDq%2FRMIwA16gUjg40DT43xDEik...xAViyc7XmzGIFBoBsNbbuN6SO1"
}

Create OAuth AT using OAM Credential Grant Type

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &username=alice
    &password=welcome
    &client_assertion=<MOBILE CLIENT ASSERTION>
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
    &oracle_device_profile=<BASE 64 ENCODING DEVICE PROFILE> 
    &oracle_use_server_device_store=true
    &scope=UserProfile.users'

Response

{
 "expires_in":3600,
 "token_type":"Bearer",
 "access_token":"eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCciO...iJSfkhhXLHhonktvigMCeI"
}

OAuth Mobile Client Three-Legged Flows

This section documents the REST calls for 3-legged mobile client flows. For more information, see "Understanding OAuth 3-Legged Authorization" and "Understanding Mobile OAuth Authorization" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

Note:

All attribute names and values are case-sensitive.

The following topics are covered in this section:

Get Application Profile

curl -i 
--request GET 'http://host:port/ms_oauth/oauth2/
endpoints/oauthservice/appprofiles/MobileApp1?device_os=iPhone%20OS&os_ver=7.000000'

Response Without Jail-Breaking Detection Policies

{
 "client_id":"MobileApp1",
 "mobileAppConfig":{
  "claimAttributes":[
    "oracle:idm:claims:client:geolocation",
    "oracle:idm:claims:client:imei",
    "oracle:idm:claims:client:jailbroken",
    "oracle:idm:claims:client:locale",
    "oracle:idm:claims:client:networktype",
    "oracle:idm:claims:client:ostype",
    "oracle:idm:claims:client:osversion",
    "oracle:idm:claims:client:phonecarriername",
    "oracle:idm:claims:client:phonenumber",
    "oracle:idm:claims:client:sdkversion",
    "oracle:idm:claims:client:udid",
    "oracle:idm:claims:client:vpnenabled",
    "oracle:idm:claims:client:fingerprint",
    "oracle:idm:claims:client:iosidforvendor",
    "oracle:idm:claims:client:iosidforad"
  ]
 },
 "oauthAuthZService":"/ms_oauth/oauth2/endpoints/oauthservice/authorize",
 "oauthNotificationService":"/ms_oauth/oauth2/endpoints/oauthservice/push",
 "oauthTokenService":"/ms_oauth/oauth2/endpoints/oauthservice/tokens",
 "oracleMobileSecurityLevel":"LOW",
 "userConsentService":["/ms_oauth/resources/consentmanagement"],
 "userProfileService":["/ms_oauth/resources/userprofile"],
 "oracleConsentServiceProtection":"OAM"
}

Response With Jail-Breaking Detection Policies

{
 "client_id":"ACMEStock",
 "jailBreakingDetectionPolicy":
 {
  "autoCheckPeriodInMin":60,
  "detectionLocation":
  [
   {"action":"exists",
    "filePath":"/bin/bash",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/Cydia.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/limera1n.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/greenpois0n.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/blackra1n.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/blacksn0w.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/redsn0w.app",
    "success":true
   },
   {"action":"exists",
    "filePath":"/Applications/sn0wbreeze.app",
    "success":true
   }
  ],
  "device_os":"iPhone OS",
  "os_ver":"7.000000",
  "policyExpirationInSec":3600
 },
 "mobileAppConfig":
 {
  "claimAttributes":[
   "oracle:idm:claims:client:geolocation",
   "oracle:idm:claims:client:imei",
   "oracle:idm:claims:client:jailbroken",
   "oracle:idm:claims:client:locale",
   "oracle:idm:claims:client:networktype",
   "oracle:idm:claims:client:ostype",
   "oracle:idm:claims:client:osversion",
   "oracle:idm:claims:client:phonecarriername",
   "oracle:idm:claims:client:phonenumber",
   "oracle:idm:claims:client:sdkversion",
   "oracle:idm:claims:client:udid",
   "oracle:idm:claims:client:vpnenabled",
   "oracle:idm:claims:client:fingerprint",
   "oracle:idm:claims:client:iosidforvendor",
   "oracle:idm:claims:client:iosidforad"
  ]
 },
 "oauthAuthZService":"/ms_oauth/oauth2/endpoints/oauthservice/authorize",
 "oauthNotificationService":"/ms_oauth/oauth2/endpoints/oauthservice/push",
 "oauthTokenService":"/ms_oauth/oauth2/endpoints/oauthservice/tokens",
 "oracleMobileSecurityLevel":"LOW",
 "userConsentService":["/ms_oauth/resources/consentmanagement"],
 "userProfileService":["/ms_oauth/resources/userprofile"],
 "oracleConsentServiceProtection":"OAM"
}

Create Mobile Device Client Verification Code

This section shows the REST request for a mobile client verification code for device registration.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=client_credentials
   &oracle_device_profile=<Base 64 Encoding Device Profile> 
   &client_id=<MobileApp1>
   &oracle_requested_assertions=oracle-idm:/oauth/assertion-type/client-identity/
mobile-client-pre-authz-code-client'

Response

{
 "expires_in":300,
 "token_type":"Bearer",
 "oracle_tk_context":"pre_azc",
 "access_token":"eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImt...5_LsQwlg7y-D8TW_0Q"
}

Create Authorization Code for Device Registration

To request an authorization code for device registration, the user-agent uses the URL shown below. In return, the authorization service sends an authorization code to the client using the redirection URI.

http://host:port/ms_oauth/oauth2/endpoints/oauthservice/
authorize?client_id=MobileApp1&redirect_uri=<Mobile App URL Scheme>
&response_type=code
&oracle_requested_assertions=urn:ietf:params:oauth:client-assertion-type:
  jwt-bearer
&oracle_pre_authz_code=<Mobile Device Client Verification Code >

Response

<Mobile App URL Scheme>?code=eyJhbGciOiJSUzUxMiIsIns93I6...A0qenJQX5rrtRpdZJl50bS0

Create Client Assertion

This request creates a mobile client assertion and a JWT user assertion. The JWT user assertion is stored in the server-side device store.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=authorization_code
    &code=<Authorization Code for Device Registration>
    &client_id=<MobileApp1>
    &redirect_uri=<Mobile App URL Scheme>
    &oracle_device_profile=<Base 64 Encoding Device Profile>

Response

{
 "oracle_client_assertion_type":"urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
 "expires_in":604800,
 "token_type":"Bearer",
 "oracle_tk_context":"client_assertion",
 "refresh_token":"eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6...7iEID1pLavdMsIg"
}

Create Mobile Device Client Verification Code

This section shows the REST request for a mobile client verification code (if required) for device registration.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:14100/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=client_credentials
   &oracle_device_profile=<Base 64 Encoding Device Profile> 
   &client_id=<MobileApp1>
   &oracle_requested_assertions=oracle-idm:/oauth/assertion-type/client-identity
/mobile-client-pre-authz-code-access'

Response

{ 
 "expires_in":300,
 "token_type":"Bearer",
 "oracle_tk_context":"pre_azc",
 "access_token":"eyJhbGciOiJSUzUxMiI4sInR5h4cCI6IkpXVCIsIm...NQXXd5_LsQy-D8TW_0Q"
}

Create Authorization Code for Access Token with Client Verification Code

To request an authorization code for device registration, the user-agent uses the URL shown below. In return, the authorization service sends an authorization code to the client using the redirection URI.

http://host.example.com:14100/ms_oauth/oauth2/endpoints/oauthservice/
authorize?client_id=MobileApp1&redirect_uri=<Mobile App URL Scheme>
&response_type=code
&scope=<Resource Scope>
&oracle_pre_authz_code=<optional Mobile Device Client Verification Code>

Response

<Mobile App URL Scheme>?code=eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVC...m_7FMwRXyEJI8J4JmPDf8RFdM7MP4_x3IBmK9amUAPRFJRNg

Create Access Token

The following request creates an OAuth Access Token if the JWT User Assertion is valid in the server-side device store.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:14100/ms_oauth/oauth2/endpoints
/oauthservice/tokens 
-d 'grant_type=authorization_code
   &code=<Authorization Code for Access Token>
   &client_id=<MobileApp1>
   &redirect_uri=<Mobile App URL Scheme>
   &oracle_device_profile=<optional base 64 encoding device profile>
   &client_assertion=<Mobile Client Assertion>
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer'

Response

{
 "expires_in":3600,
 "token_type":"Bearer",
 "refresh_token":"eyJhbGiiIsInR5cCI6IkpXVCmtaWRfdHlwZSI6IBfVUDM5Qi00Q0U3LUxyJ6ndU"
}

OAM Token Exchange and Credential-Based (Including PIN-Based) Authentication

This section documents the REST calls you use for OAM token exchange.

Note:

All attribute names and values are case-sensitive.

The following topics are covered in this section:

Using a Client Credential + User Name and Password Combination

This section documents how to use a client credential together with a user name and password to get the following token types: a JWT user token, a JWT access token, an OAM user token and master token, or an OAM access token.

The following topics are covered in this section:

Overview

Requests in this section use the following basic template.

curl -i 
-H 'Authorization: Basic <sample client ID and password>' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/
endpoints/oauthservice
 /tokens
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
   &username=<username>
   &password=<password>
   &oracle_requested_assertions=<Oracle_Requested_Assertion_Type>
   &oam_authen_resource=<oam_authen_resource>'

Note the following:

  • The sample client ID and password takes the following form:

    userID123:password123

    --> base 64 encoding -->

    NTQzMjFpZDp3ZWxjb21lMQ==

    The actual client ID will be a machine generated GUID.

  • You can specify the following assertion types:

    • oracle-idm%3A%2Foauth%2Fassertion-type%2Fuser-identity%2Foam

    • oracle-idm%3A%2Foauth%2Fassertion-type%2Fuser-identity%2Fjwt

  • Use the oam_authen_resource optional parameter to specify the authentication resource name configured on the OAM server side.

How to Get a JWT User Token

$ curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &username=user123
    &password=passwordAbc12323
    &oracle_requested_assertions=
   oracle-idm%3A%2Foauth%2Fassertion-type%2Fuser-identity%2Fjwt'

How to Get a JWT Access Token

$ curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &username=user123
    &password=passwordAbc123
    &scope=ConsentManagement.retrieve ConsentManagement.grant ConsentManagement.revoke'

How to Get an OAM User Token and Master Token

$ curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &username=user123
    &password=passwordAbc123'

Using a Client Credential + oracle_user_credentials Combination

This section documents how to use a client credential together with the oracle_user_credentials value to get the following token types: a JWT user token, a JWT access token, an OAM user token and master token, or an OAM access token.

The following topics are covered in this section:

Overview

Requests in this section use the following basic template.

curl -i 
-H 'Authorization: Basic <sample client ID and password>' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &oracle_user_credentials=<ORACLE_USER_CREDENTIALS>
    &oracle_requested_assertions=<Oracle_Requested_Assertion_Type>
    &oam_authen_resource=<oam_authen_resource>'

Note the following:

  • The oracle_user_credentials take the following form:

    {"userid":"user123","password":"password123"}
    

    >> Base64 encoded value of JSON data >>

    eyJ1c2VyaWQiOiJ3ZWJsb2dpYyIsInBhc3N3b3JkIjoid2VsY29tZTEifQ==
    

    The actual client ID will be a machine generated GUID.

  • You can specify the following assertion types:

    • oracle-idm%3A%2Foauth%2Fassertion-type%2Fuser-identity%2Foam

    • oracle-idm%3A%2Foauth%2Fassertion-type%2Fuser-identity%2Fjwt

  • Use the oam_authen_resource optional parameter to specify the authentication resource name configured on the OAM server side.

How to Get a JWT User Token

$ curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
   &oracle_user_credentials=eyJ1c2VyaWQiOiJ3ZWJsb2dpYyIsInBhc3N3b3JkIjoid2VsY29tZT
EifQ==
   &oracle_requested_assertions=oracle-idm%3A%2Foauth%2Fassertion-type%2F
user-identity%2Fjwt'

How to Get a JWT Access Token

$ curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
   &oracle_user_credentials=eyJ1c2VyaWQiOiJ3ZWJsb2dpYyIsInBhc3N3b3JkIjoid2VsY29t
ZTEifQ==
   &scope=ConsentManagement.retrieve ConsentManagement.grant ConsentManagement.revoke'

How to Get an OAM User Token and Master Token

$ curl -i 
-H 'Authorization: Basic NTQzMjFpZDp3ZWxjb21lMQ==' 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
   &oracle_user_credentials=<base64_encoded_credential>
   &client_assertion=<client_jwt_assertion or client_saml2_assertion>
   &client_assertion_type=<client_assertion_type>
   &oracle_requested_assertions=<Oracle_Requested_Assertion_Type>'

Using JWT Assertion

This section documents how to use a JWT assertion to get the following token types: a JWT user token, a JWT access token, an OAM user token and master token, or an OAM access token.

The following topics are covered in this section:

Overview

Requests in this section use the following basic template.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host:port/ms_oauth/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials

How to Get a JWT User Token

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &user_oracle_credentials=<base64_encoded_credentials>
    &client_assertion=eyJhbGciOiJSUzUxMiIsjiRZ1_3edKknPTCEtQS79h_44H_8VbGvnA6Dr3M0
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type
%3Ajwt-bearer
    &oracle_requested_assertions=oracle-idm%3A%2Foauth%2Fassertion-type%2F
user-identity%2Fjwt'

How to Get a JWT Access Token

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauthservice/tokens
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials&    
    &user_assertion=<JWT User assertion Value>
    &user_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Auser-assertion-type%3Ajwt-bearer
    &client_assertion=eyJhbGciOiJSUzUxMiIsInR5cCI6Ik...j5mZJrfrwxgXxzwVcNbjRgi7uM8
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer'

How to Get an OAM User Token and Master Token

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &user_assertion=<JWT User assertion Value>
    &user_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Auser-assertion-type
%3Ajwt-bearer
   &client_assertion=eyJhbGciOiJSUzUxMiIsInR5cCI6Ik...j5mZJrfrwxgXxzwVcNbjRgi7uM8
   &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
client-assertion-type%3Ajwt-bearer
   &oracle_device_profile=eyJvcmFjbGU6aWRtOmNsYWltczpjbGllbnQ6c2Rrd...1zOmNvc3ZlcnNpb24iOiI0LjAifQ==
   &oracle_use_server_device_store=true'

How to Get an OAM Access Token With an OAM User Token Located in the Server-Side Key Store

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
   &oracle_use_server_device_store=true
   &user_assertion_type=oracle-idm%3A%2Foauth%2Fassertion-type%2Fuser-identity%2oam
   &client_assertion=eyJhbGciOiJSR5cCI6IkpXVCIsIm...UBaJkagXsLbqb_fNJHqNfwe3QCr7Uk
   &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
   &oracle_device_profile=eyJvcmFjbtczpjbGllbnQ6c2Rrdm...pc3ZlcnNpb24iOiI0LjAifQ==
   &scope=oracle.security.oauth.oam.resource_access
   &oracle_oam_application_context=dfsdfsdfsdfsdf
   &oracle_oam_application_resource=http%3A%2F%2Fhost123.example.com%3A12884%2Findex.html'

Using JWT Assertion + PIN

This section documents how to use a JWT user assertion and a PIN (or PIN-like user credential) to get an OAM user token and OAM master token. The client can specify the PIN or passcode value (as an additional credential) together with a JWT user assertion in the request.

The following topics are covered in this section:

Overview

Requests in this section use the following basic template:

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
–request http://host.example.com:14100/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &oracle_user_credentials=<Base64 encoded PIN Value>
    &client_assertion=<JWT Client Assertion>
    &client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
    &oracle_user_credentials=<BASE64 ENCODED USER CREDENTIALS>
    &user_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%3Auser-assertion-type%3Ajwt-bearer
    &oracle_device_profile=<BASE64 ENCODING DEVICE PROFILE>'

The oracle_user_credentials parameter is optional. It is a Base64-encoded value of JSON data that can contain any pair of name and value. For example:

{"pin":"pinvalue123"} encodes to eyJwaW4iOiJwaW52YWx1ZTEyMyJ9

Response

{
  "oracle_aux_tokens":{
    "oam_mt":{
      "oracle_tk_context":"oam_mt",
      "oracle_grant_type":"oracle-idm:\/oauth\/grant-type\/oam\/master-token",
      "access_token":""
    }
  },
  "oracle_tk_context":"oam_ut",
  "oracle_grant_type":"oracle-idm:\/oauth\/grant-type\/user-token\/oam",
  "access_token":""
}

How to Get an OAM User Token and Master Token

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
request http://host.us.example.com:14100/ms_oauth/oauth2/endpoints/oauthservice/tokens  
-d '
     grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &user_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%3Auser-assertion-type%3Ajwt-bearer
    &oracle_user_credentials=eyJwaW4iOiJwaW52YWx1ZTEyMyJ9
    &client_assertion=eyJhbGciOiJSUzI1NiIs...jOGVj0GXMCA
    &client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
    &oracle_device_profile=ew0KICAgIm9yYWNsZTppZG0...fQ0K
    &user_assertion=eyJhbGciOiJSUzI1NiIsInR5...UyFT7Y9eeo5af4OA
   '

Response

{
  "oracle_aux_tokens":
   {
    "oam_mt":
     {
      "oracle_tk_context":"oam_mt",
      "oracle_grant_type":"oracle-idm:\/oauth\/grant-type\/oam\/master-token",
      "access_token":"VERSION_4%7ELw3jGjxe...F6wouV7ow"
     }
   },
  "oracle_tk_context":"oam_ut",
  "oracle_grant_type":"oracle-idm:\/oauth\/grant-type\/user-token\/oam",
  "access_token":"E6Fyeco+F0GgucHJuLmlkX3R5c...DC0dsLVdJYyJ3Su2xpZWB3"}

Using SAML2 Assertion

This section documents how to use a SAML2 assertion to get the following token types: a JWT user token, a JWT access token, an OAM user token and master token, or an OAM access token.

The following topics are covered in this section:

Overview

Requests in this section use the following basic template.

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host123.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &oracle_user_credentials=<base64_encoded_value>
    &client_assertion=<client_jwt_assertion or client_saml2_assertion>
    &client_assertion_type=<client_assertion_type>
    &oracle_requested_assertions=<Oracle_Requested_Assertion_Type>'

How to Get a JWT User Token

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &oracle_user_credentials=<base64_encoded_value>
    &client_assertion=PHNhbWw6QXNzZXJ0aW9uI...2ln%0AbmF0dXJltbDpBc3NlcnRpb24%2B%0A
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type
%3Asaml2-bearer
    &oracle_requested_assertions=oracle-idm%3A%2Foauth%2Fassertion-type
%2Fuser-identity%2Fjwt'

How to Get a JWT Access Token

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &oracle_user_credentials=<base64_encoded_value>
    &client_assertion=PHNhbWw6QXNzZXJ0aW9...uIHhtbG5zOnNhhbWwc3NlcnRpb24%2B%0A
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type
%3Asaml2-bearer&scope=ConsentManagement.retrieve'

How to Get an OAM User Token and Master Token

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &oracle_user_credentials=<base64_encoded_value>
    &client_assertion=PHNhbWw6QXNzZXJ0aW9uIHhtb9InVyb...2BPC9zYW1sOkF0dHJpYnV0ZT48
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type
%3Asaml2-bearer'

OAM Token Exchange on Mobile Devices

This section documents how to get an OAM user token and master token, or an OAM access token on mobile devices.

The following topics are covered in this section:

How to Request a Verification Code

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=client_credentials
    &oracle_device_profile=eyJvcmFjbGU6aWRtOmNsYWltczpjbGllbnQ6c2RrdmVyc2l...OmNsaWVudDpvc3ZlcnNpb24iOiI0LjAifQ==
    &client_id=<MobileAgent1>
    &oracle_requested_assertions=oracle-idm%3A%2Foauth%2Fassertion-type
%2Fclient-identity%2Fmobile-client-pre-authz-code-client'

How to Register the Client

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/oauthservice/tokens 
-d 'grant_type=password&username=userAbc123
    &password=passwordAbc123
    &client_id=<MobileAgent1>
    &oracle_pre_authz_code=eyJhbGci...SsLRxbAt8Yl473vBACuH2Ms2fR_HwhQGVu_zgI3W3a_c
    &oracle_device_profile=eyJvcmFjbGU6aWRtOmNsYWl...G06Y2xhaW1zOmNsaWViI0LjAifQ==
    &oracle_requested_assertions=urn%3Aietf%3Aparams%3Aoauth
%3Aclient-assertion-type%3Ajwt-bearer'

How to Get an OAM User Token and Master Token

$ curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth9%2Fgrant-type%2Foam_credentials
    &user_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Auser-assertion-type%3Ajwt-bearer
    &client_assertion=eyJhbGciOiJSUzUxMiIsInR5cCI...qwzcgoh5t7sfZInGkbprlA5UswMzqk
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type
%3Ajwt-bearer
    &oracle_device_profile=eyJvcmFjbGU6aWRtOmNsYWltczpjbG...udDnNpb24iOiI0LjAifQ==
    &oracle_use_server_device_store=true'

How to Get an OAM Access Token

curl -i 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
--request POST http://host.example.com:18001/ms_oauth/oauth2/endpoints/
oauthservice/tokens 
-d 'grant_type=oracle-idm%3A%2Foauth%2Fgrant-type%2Foam_credentials
    &client_assertion=eyJhbGciOiJSUzUxMiIs...6NxPv0x_Ng2pEcjVJf42p-tiBFClavI56ycCg
    &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type
%3Ajwt-bearer
    &oracle_device_profile=eyJvcmFjbGU64czpjbGllbnQ6c...ivc3ZlcnNpb24iOiI0LjAifQ==
    &user_assertion_type=oracle-idm%3A%2Foauth%2Fassertion-type%2Fuser-identity
%2Foam
    &scope=oracle.security.oauth.oam.resource_access
    &oracle_oam_application_context=fdsfsdfsdfsdf
    &oracle_oam_application_resource=http%3A%2F%2Fhost123.example.com
%3A12884%2Findex.html
    &oracle_use_server_device_store=true'