REST API for Oracle Mobile Cloud Service

Exchange Token

post

/mobile/platform/auth/token

Exchange an external identity provider token for an OAuth mobile user token.

In addition to providing a user assertion that authenticates the user, you must use one of the following to authenticate the client that is sending the request:

Set the Authorization header to Basic base64-encoded-client-id:client-secret.
Don't include an Authorization header and provide the client ID and client secret in the form data. If you configure the Security_AuthTokenConfiguration policy to not require the client secret for the external token issuer, then you can omit the client secret.
Don't include an Authorization header and provide a client assertion and client assertion type in the form data.

Request

Supported Media Types

multipart/form-data

Root Schema : schema

Type: object

Show Source

assertion: string

The assertion (access_token) that you get from the external identity provider.

Example: eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
client_assertion(optional): string

The client assertion for client authentication (if applicable). To get a client assertion, send a request to the backend's OAuth token endpoint. Set the content type to application/x-www-form-urlencoded. Use Basic base64-encoded-client-id:client-secret for the Authorization header. Set the body to grant_type=client_credentials. Use the returned access_token for the client_assertion value.

Example: eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
client_assertion_type(optional): string

The type of client assertion provided for client authentication (if applicable). Currently, `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` is supported.

Example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_id(optional): string

The backend's client ID. This is shown in the UI on the backend's Settings page.

Example: 9ZJ4M-BdOqsNQ-xlAJuMF7
client_secret(optional): string

The backend's client secret. This is shown in the UI on the backend's Settings page.

Example: k7GQT9-izOBajNKS-6Jw2B
grant_type: string

OAuth grant type. Currently, urn:ietf:params:oauth:grant-type:jwt-bearer is supported.

Example: urn:ietf:params:oauth:grant-type:jwt-bearer

{
    "properties":{
        "client_secret":{
            "description":"The backend's client secret. This is shown in the UI on the backend's Settings page.\n",
            "example":"k7GQT9-izOBajNKS-6Jw2B",
            "type":"string"
        },
        "client_assertion_type":{
            "description":"The type of client assertion provided for client authentication (if applicable).\nCurrently, `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` is supported.\n",
            "example":"urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            "type":"string"
        },
        "grant_type":{
            "description":"OAuth grant type.\nCurrently, <code>urn:ietf:params:oauth:grant-type:jwt-bearer</code> is supported.\n",
            "example":"urn:ietf:params:oauth:grant-type:jwt-bearer",
            "type":"string"
        },
        "client_assertion":{
            "description":"The client assertion for client authentication (if applicable).\nTo get a client assertion, send a request to the backend's OAuth token endpoint.\nSet the content type to <code>application/x-www-form-urlencoded</code>.\nUse <code>Basic <i>base64-encoded-client-id:client-secret</i></code> for the <code>Authorization</code> header. Set the body to <code>grant_type=client_credentials</code>.\nUse the returned <code>access_token</code> for the <code>client_assertion</code> value.\n",
            "example":"eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
            "type":"string"
        },
        "client_id":{
            "description":"The backend's client ID. This is shown in the UI on the backend's Settings page.\n",
            "example":"9ZJ4M-BdOqsNQ-xlAJuMF7",
            "type":"string"
        },
        "assertion":{
            "description":"The assertion (<code>access_token</code>) that you get from the external identity provider.\n",
            "example":"eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
            "type":"string"
        }
    },
    "type":"object",
    "required":[
        "grant_type",
        "assertion"
    ]
}

Response

Supported Media Types

application/json

200 Response

The OAuth user access token was generated successfully.

Access token response.

Root Schema : accessTokenResponse

Type: object

Access token response.

Show Source

access_token: string

The access token issued by the authorization server.
expires_in(optional): string

The lifetime in seconds of the access token. For example, the value `3600` denotes that the access token expires in one hour from the time the response was generated.
id_token(optional): string

Currently not used.
token_type: string

The type of the token issued. For example, `Bearer`.

{
    "description":"Access token response.",
    "properties":{
        "token_type":{
            "description":"The type of the token issued. For example, `Bearer`.",
            "type":"string"
        },
        "expires_in":{
            "description":"The lifetime in seconds of the access token. For example, the value `3600` denotes that the access token expires in one hour from the time the response was generated.",
            "type":"string"
        },
        "id_token":{
            "description":"Currently not used.",
            "type":"string"
        },
        "access_token":{
            "description":"The access token issued by the authorization server.",
            "type":"string"
        }
    },
    "required":[
        "access_token",
        "token_type"
    ],
    "type":"object"
}

Example Response (application/json)

{
    "token_type":"Bearer",
    "expires_in":28800,
    "id_token":null,
    "access_token":"eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

401 Response

Unauthorized request. The response body typically follows RFC7521 standards.

Example Response (application/json)

{
    "error":"invalid_client",
    "error_description":"No client secret was provided (Issuer: someIssuer)"
}

404 Response

Backend not found.

Root Schema : Error

Type: object

Title: Error

The error JSON object returned by Mobile Cloud Service.

Show Source

detail: string

Message that provides the error details.
o:ecid: string

Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
o:errorCode: string

Mobile Cloud Service error code.
o:errorDetails(optional): array o:errorDetails

Minimum Number of Items: 0

List of the issues that cause the error. Included when the error is caused by multiple issues.
o:errorPath: string

The relative point in the API path where the error occurred.
status: integer

HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
title: string

Summary of the problem.
type: string

The URI to the link that provides details about the HTTP status code.

{
    "title":"Error",
    "description":"The error JSON object returned by Mobile Cloud Service.",
    "properties":{
        "title":{
            "description":"Summary of the problem.",
            "type":"string"
        },
        "detail":{
            "description":"Message that provides the error details.",
            "type":"string"
        },
        "status":{
            "description":"HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.",
            "type":"integer"
        },
        "o:errorCode":{
            "description":"Mobile Cloud Service error code.",
            "type":"string"
        },
        "o:errorPath":{
            "description":"The relative point in the API path where the error occurred.",
            "type":"string"
        },
        "o:errorDetails":{
            "items":{
                "$ref":"#/definitions/errorDetail"
            },
            "description":"List of the issues that cause the error. Included when the error is caused by multiple issues.",
            "minItems":0,
            "type":"array"
        },
        "o:ecid":{
            "description":"Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.",
            "type":"string"
        },
        "type":{
            "description":"The URI to the link that provides details about the HTTP status code.",
            "type":"string"
        }
    },
    "required":[
        "type",
        "status",
        "title",
        "detail",
        "o:ecid",
        "o:errorCode",
        "o:errorPath"
    ],
    "type":"object"
}

Nested Schema : o:errorDetails

Type: array

Minimum Number of Items: 0

List of the issues that cause the error. Included when the error is caused by multiple issues.

Show Source

Array of: object Error Detail

Title: Error Detail

{
    "items":{
        "$ref":"#/definitions/errorDetail"
    },
    "description":"List of the issues that cause the error. Included when the error is caused by multiple issues.",
    "minItems":0,
    "type":"array"
}

Nested Schema : Error Detail

Type: object

Title: Error Detail

Show Source

instance: string

The URI to the link that provides more detailed information about the error.
o:errorCode: string

Mobile Cloud Service error code.
o:errorPath: string

The relative point in the API path where the error occurred.
title: string

Summary of the problem.
type: string

The URI to the link that provides details about the HTTP status code.

{
    "title":"Error Detail",
    "properties":{
        "title":{
            "description":"Summary of the problem.",
            "type":"string"
        },
        "o:errorPath":{
            "description":"The relative point in the API path where the error occurred.",
            "type":"string"
        },
        "o:errorCode":{
            "description":"Mobile Cloud Service error code.",
            "type":"string"
        },
        "type":{
            "description":"The URI to the link that provides details about the HTTP status code.",
            "type":"string"
        },
        "instance":{
            "description":"The URI to the link that provides more detailed information about the error.",
            "type":"string"
        }
    },
    "required":[
        "type",
        "instance",
        "title",
        "o:errorPath",
        "o:errorCode"
    ],
    "type":"object"
}

Example Response (application/json)

{
    "title":"Mobile Backend not found",
    "detail":"We cannot find the active mobile backend for the given clientId 9ZJ4M-BdOqsNQ-xlAJuMF7 and OAUTH schema. Specify a valid clientId and try again.",
    "status":404,
    "o:errorCode":"MOBILE-58026",
    "o:errorPath":"/mobile/platform/auth/token",
    "o:ecid":"005978mvJuc2rIGpIwDCif00070J0000Bd, 0:2",
    "type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1"
}

Examples

Examples of Request Body

Here are examples for the three ways to authenticate when you send a request to exchange an identity provider token for an OAuth mobile user token using cURL. For more information about cURL, see Use cURL

Pass the Client ID and Client Secret in the Authorization Header

curl -i \
-X POST   \
-d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer'  \
-d 'assertion=eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' \
-H 'Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0'  \
-H 'Oracle-Mobile-Backend-ID: ABCD59b-f13c-4722-81b8-4e719b5a4622' \
-H "Content-Type: application/x-www-form-urlencoded" \
http://fif.cloud.oracle.com/mobile/platform/auth/token

Pass the Client ID and Client Secret in the Form Data

Note that the Authorization header isn't included in the request.

curl -i \
-X POST   \
-d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer'  \
-d 'assertion=eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' \
-d 'client_id=Y2xpZW50aWQ=' \ 
-d 'client_secret=Y2xpZW50c2VjcmV0' \
-H 'Oracle-Mobile-Backend-ID: ABCD59b-f13c-4722-81b8-4e719b5a4622' \
-H "Content-Type: application/x-www-form-urlencoded" \
http://fif.cloud.oracle.com/mobile/platform/auth/token

Pass the Client Assertion and Client Assertion Type in the Form Data

Note that the Authorization header isn't included in the request.

curl -i \
-X POST   \
-d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer'  \
-d 'assertion=eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' \
-d 'client_assertion=eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' \ 
-d 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
-H 'Oracle-Mobile-Backend-ID: ABCD59b-f13c-4722-81b8-4e719b5a4622' \
-H "Content-Type: application/x-www-form-urlencoded" \
http://fif.cloud.oracle.com/mobile/platform/auth/token

Example of Response Header

The following shows an example of the response header:

200 OK
Content-Length: 100
Content-Type: application/json
Date: Mon, 30 Jan 2017 20:32:51 GMT

Example of Response Body

The following example shows the contents of the response body in JSON format:

{
    "token_type":"Bearer",
    "expires_in":28800,
    "id_token":null,
    "access_token":"eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}