REST API for Oracle Fluid Recruiting Cloud

OAuth Essentials

OAuth in Oracle Taleo is accomplished by defining an OAuth Client and Resources. The customer will have a Client ID and a Client Secret that the customer's application will use when reaching to Oracle Taleo to identify itself. The entities in OAuth are as follows:

Resource owner - user, who has an account in TEE and authorized to access the public API
Resource server - Public API, this is the Oracle Taleo instance.
Authorization server - Oracle Taleo Smartorg
Client - Customer application that request access to the Public API.

OAuth Authorization Code Grant flow

Oracle Taleo supports the Authorization Code Grant flow for the public API clients. This flow involves the usage of three tokens:

Authorization code
Access token
Refresh token

The flow to complete the access to the requested Resource is:

The Client Application will redirect the User to Oracle Taleo SmartOrg, which acts as the Authorization Server.
The User will enter his credentials and, upon successful authentication, SmartOrg will generate the Authorization Code.
The Resource Owner's Browser will send the Authorization Code to the Client Application.
The Client Application will contact SmartOrg and present the three codes required to get the Access Token:
- Authorization Code or Refresh Token
- Client ID
- Client Secret
SmartOrg will return an Access Token and a Refresh Token to the Client Application.
The Client Application will use the Access Token to access the requested Resource.

images/oauth.png

The Authorization Code, the Access Token, and the Refresh Token all have a validity period. The OAuth flow handles each differently.

Authorization Code

If an expired code is used, SmartOrg will return an error message.

To get a new one, the OAuth flow has to be reinitiated from the beginning.

Access Token

When the token expires, the Client Application will use the Refresh Token to get a new Access Token.

It will also receive a new Refresh Token.

Refresh Token

If an expired Refresh Token is used, SmartOrg will return an error message.

Restarting the OAuth flow will generate a new one.

The Refresh Token removes the need for the Resource Owner to authenticate anew when the Client Application makes multiple requests to the Resources. It removes the need to the Resource Owner to authenticate each time.

Client Registration

A client is a customer application. Each zone can have multiple clients registered for OAuth through the OAuth management interface. Oracle Support personnel manages client registration in the Oracle Taleo zone.

The customer has to provide the following information to Oracle Support personnel to complete the registration process.

Redirect URI - HTTPS URI where the authorization service would redirect the user with the authorization code.

Once the client registration is successful, Support personnel will share the following information to the customer:

Client ID
Client Secret

OAuth Endpoints

Authorization Code

The client application gets the authorization code after the user successfully authenticated.

response_type	REQUIRED. Value MUST be set to "code."
client_id	REQUIRED. The client identifier received from support.
redirect_uri	REQUIRED. HTTPS uri where the authorization service would redirect the user with the authorization code.
state	RECOMMENDED. A 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. Example: `GET /smartorg/oauth/authorize?response_type=code&client_id=970ca327ed6a57ff& state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 Host: example.taleo.net`

Authorization Response

Upon successful authentication of resource owner, 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-formurlencoded" format.

code

REQUIRED.

The authorization code generated by the authorization server. The authorization code expires shortly after it is issued to mitigate the risk of leaks. The authorization code is valid for only one access token request.

state

REQUIRED.

If the "state" parameter was present in the client authorization request, it will be present in the response. It will be the exact value received in the request.

Successful Response example:

Authorization server redirects the user-agent by sending the following HTTP response:

HTTP/1.1 302 
    Found Location:
    https://client.example.com/cb?code=2EEcuWG8JpwE3iWLOWLahQ%3D%3D&state=xyz
    Error Response examples: 
    Invalid Client
    Invalid redirectURI 
    Missing Parameter: ClientId
    Missing response_type parameter value

Request Access Token

The client application posts the code along with the client credentials to the authorization server to get an access token.

Access Token Request

The client makes a request to the token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body.

grant_type

REQUIRED.

Value MUST be set to "authorization_code".

code

REQUIRED.

The authorization code received from the authorization server during the authorize call.

redirect_uri

REQUIRED,

The same "redirect_uri" parameter included in the authorization request.

For example, the client makes the following HTTP request using TLS:

POST 
    /smartorg/oauth/token HTTP/1.1
    Host: example.taleo.net
    Authorization: Basic
    OTcwY2EzMjdlZDZhNTdmZjpkYjljZmMxZmJiYWE3ZjkzMmU3M2JhNThiMjZiMWEzZA
    Content-Type: application/x-www-form-urlencoded 
    grant_type=authorization_code&code=2EEcuWG8JpwE3iWLOWLahQ%3D%3D&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Note:

Authorization header in the above request is Base64 encoded value of ClientID:ClientSecret

Access Token Response

If the access token request is valid and authorized, the authorization server issues an access token. If the client authentication failed or is invalid, the authorization server returns an error response.

Successful response example:

HTTP/1.1 200 OK
{
    "access_token": "uLOOogmZfqAJBO16SYIpjJ8P2qS+gnb8PAoWgcVF4oE=",
    "refresh_token": "eVNFMDlBOUNHNkpnNlZzVndLMEsxUEtqMjBMYTJUSlc=",
    "login_name": "testUser",
    "token_type": "Bearer",
    "expires_in": 10800000
}

Note:

The above token expires in 10800000 milliseconds, i.e.180 minutes.

Error responses:

Invalid_request sample

{
    "error_description": "Missing grant_type parameter value",
    "error": "invalid_request" 
    }
{ 
    "error_description": "Missing parameters: redirect_uri",
    "error": "invalid_request" 
}
{ 
    "error_description": "Invalid grant_type parameter value",
    "error": "invalid_request" 
}

Invalid_grant sample:

{
    "error_description": "Invalid RedirectURI",
    "error": "invalid_grant" 
}

invalid_client sample:

{ 
    "error_description": "Client authentication failed.",
    "error": "invalid_client" 
}

unauthorized_client sample:

{ 
    "error_description": "Client authentication failed.",
    "error": "unauthorized_client" 
}

Revoke Access Token

The client application can send the revocation request by including the following parameters using the

"application/x-www-form-urlencoded" format in the HTTP request entity body.

token

REQUIRED.

The token that the client wants to revoke.

For example, a client may request the revocation of an access token with the following request:

POST /smartorg/oauth/revoke HTTP/1.1 
Host:example.taleo.net 
Content-Type: application/x-www-form-urlencoded 
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=uLOOogmZfqAJBO16SYIpjJ8P2qS+gnb8PAoWgcVF4oE=

Note:

Authorization header in the above request is Base64 encoded value of ClientID:ClientSecret

Refresh Access Token

The client application posts the refreshtoken along with the client credentials to the authorization server to get an access token.

Refresh Token Request

The client makes a request to the token endpoint by sending the following parameters using the "application/xwww- form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body.

grant_type

REQUIRED.

Value MUST be set to "refresh_token."

refresh_token

REQUIRED.

The refresh_token received from the authorization server during the accesToken call.

For example, the client makes the following HTTP request:

POST /smartorg/oauth/token HTTP/1.1
    Host: example.taleo.net
    Authorization: Basic
    OTcwY2EzMjdlZDZhNTdmZjpkYjljZmMxZmJiYWE3ZjkzMmU3M2JhNThiMjZiMWEzZA
    Content-Type: application/x-www-form-urlencoded
    grant_type= refresh_token &refresh_token= eVNFMDlBOUNHNkpnNlZzVndLMEsxUEtqMjBMYTJUSlc=

Note:

Authorization header in the above request is Base64 encoded value of ClientID:ClientSecret

Refresh Token Response

If the refresh token request is valid and authorized, the authorization server issues an access token. If the client authentication failed or is invalid, the authorization server returns an error response.

Successful response example:

HTTP/1.1 200 OK
{
    "access_token": "V0paVU1qWkZiZmJFRzREbDdSQ3JFN0RsTnpyS01SbEc=",
    "login_name": "testUser",
    "token_type": "Bearer",
    "expires_in": 1800000
}

Note:

The above token expires in 10800000 milliseconds, (180 minutes).

Error Responses

Invalid_request sample:

{
    "error_description": "Missing grant_type parameter value",
    "error": "invalid_request"
}
{
    "error_description": "Invalid grant_type parameter value",
    "error": "invalid_request"
}

Invalid_client sample:

{
    "error_description": "Client authentication failed.",
    "error": "invalid_client"
}

Unauthorized_client sample:

{
    "error_description": "Client authentication failed.",
    "error": "unauthorized_client"
}