Authenticate with Server and Get Access Token
/iot/api/v2/oauth2/token
This API implements the the OAuth2 client credentials grant flow, which enables clients to obtain an access token by authenticating themselves. The client credentials flow is used when the client itself owns the data and does not need delegated access from a resource owner, or when delegated access has been provided outside of the OAuth2 flow. This flow relies on the client to authenticate with the server, and the client's authentication credentials remain confidential.
This API supports the following authentication mechanisms:
- client_assertion: used by the client that asserts its identity using a JSON Web Token (JWT). The JWT contains the signature that proves the possession of the private key.
The OAuth2 scope attribute is required for all requests for access tokens. The server supports the following scopes:
- scope=oracle/iot/activation: used to obtain an access token for calling Activation REST APIs only
- scope=empty scope, used to obtain an access token for calling all other REST APIs
Any other scope value results in a BAD_REQUEST error.
JSON Web Token (JWT)
An open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA.
JSON Web Tokens consist of three parts separated by dots (.
), which are:
- Header
- Payload
- Signature
Therefore, a JWT typically looks like the following.
xxxxx.yyyyy.zzzzz
Header
The header for authentication consists of two parts: the type of the token, which is JWT, and the hashing algorithm such as HmacSHA256 ("HS256") or SHA256withRSA ("RS256").
Payload
The second part of the token is the payload, which contains the claims about the Device Endpoint.
Required claims: These are a set of required claims for authentication:
- iss (issuer, should be the Device Activation ID for Activation purpose and Device Endpoint Id for Messaging purpose)
- exp (expiration time, the epoch value in seconds. If the expiration time is outside a 30 minute window, the request is rejected)
- aud (audience, should be "oracle/iot/oauth2/token").
Signature
To create the signature part you have to take the encoded header, the encoded payload, a key, the algorithm specified in the header, and sign that in the following way:
Algorithm(base64UrlEncode(header) + "." +base64UrlEncode(payload), key)
Note HmacSHA256 is only used in the activation procedure (scope=oracle/iot/activation), and the key used for the signature is the shared secret of the Device Endpoint. SHA256withRSA is used in other procedures (scope is empty), such as posting a message, and the secret key of the Device Endpoint is used as the key for signature.
Request
- application/x-www-form-urlencoded
-
client_assertion(optional): string
The client assertion data as a JWT token.
-
client_assertion_type(optional): string
The client assertion type. The value MUST be
urn:ietf:params:oauth:client-assertion-type:jwt-bearer
. -
grant_type: string
The grant type. For the client credentials flow, the value MUST be client_credentials.
-
scope(optional): string
The scope of the access token request. The value MUST be empty or
oracle/iot/activation
.
Response
- application/json
200 Response
object
-
access_token:
string
The access token (for example, 8vsdettdjjjdc-aggdgsgcbbsgd)
-
expires_in(optional):
integer(int64)
Time in miliseconds for the access token to expire (for example, 3600000)
-
token_type(optional):
string
The type of the access token issued (for example, Bearer). This value MUST be specified in the Authorization header in the HTTP request.
400 Response
401 Response
403 Response
Examples
The following shows you two examples, one on how to get an activation token and another on how to get a message token from the IoT Cloud Service instance.
Get Activation Token
The following shows an example of a request header:
Content-Type: application/x-www-form-urlencoded Accept: application/json
Example of Request Form Parameters
The following shows an example of form parameters:
grant_type=client_credentials client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwLVlRRlEiLCJleHAiOjE0Njc3NjYyNjMsImF1ZCI6Im9yYWNsZS9pb3Qvb2F1dGgyL3Rva2VuIn0.AU9eYChN9EOupzyLoWf0AMZ0QiK4dnmpA1n5tb_kSSw scope=oracle/iot/activation
Example of cURL
Command
cURL
to send a client assertion to get an access token for performing activation operations on Device
with Activation ID=6e5e3e593bcf-1c79
. The activation secret of the device is
secret
, and the state is
REGISTERED
. The JWT token for
client_assertion
contains the following information:
Header: { "typ": "JWT", "alg": "HS256" } Payload: { "iss": "6e5e3e593bcf-1c79", "exp": 1467751899, "aud": "oracle/iot/oauth2/token" }
The signature is obtained from signing the "Header.Payload" by the HmacSHA256
algorithm using "secret" as the key. This algorithm is typically used during device activation.
The JSON Web Token Builder site might help you construct a valid JWT token.
Note that in the request, http://iotserver
will be replaced by the name and port of your assigned IoT Cloud Service instance. The format of the Cloud Service instance is https://myinstance-myidentitydomain.iot.us.oraclecloud.com
and the default port is 443
.
For more information about cURL, see Use cURL.
curl -X POST -H 'Accept:application/json' -H 'Content-Type: application/x-www-form-urlencoded' --data "grant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwLVlRRlEiLCJleHAiOjE0Njc3NjYyNjMsImF1ZCI6Im9yYWNsZS9pb3Qvb2F1dGgyL3Rva2VuIn0.AU9eYChN9EOupzyLoWf0AMZ0QiK4dnmpA1n5tb_kSSw&scope=oracle/iot/activation" http://iotserver/iot/api/v2/oauth2/token
Example of Response Header
The following shows an example of the response header when the request is successful.
HTTP/1.1 200 OK Content-Type: application/json
Example of Response Body
The following example shows the contents of the response body containing the expiration time, token type, and token value in JSON format.
{ "expires_in":3600000, "token_type":"Bearer", "access_token":"677b4afa55236110825ae0a3d38275ad" }
Get Message Token
The following shows an example of a request header:
Content-Type: application/x-www-form-urlencoded Accept: application/json
Example of Request Form Parameters
grant_type=client_credentials
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJBQUFBQUFRMEZSMEEtQ0UiLCJhdWQiOiJvcmFjbGUvaW90L29hdXRoMi90b2tlbiIsImV4cCI6MTQ2OTQ3NDE5M30.oDiGi13Xw1ZJJ3iMDOSpZLN1NNfTVF8wJuWy2sMzcKKVIUbULeFCUoyd8SZiJBXMQDd4n_dRtF5vq7or3kGGiKOiWkS3V-r1qqqL0-o02Hh2tQ4AOHvwMRbEQOGE3lA7doNRd9sr7BR5zQGu4yahCh5581Q_4B5gV-ZN65gbdt4
scope=
Example of cURL
Command
cURL
to send a client assertion to get an access token for performing activation operations on Device
with Endpoint ID=0-AECA
. The device is already
ACTIVATED
. The JWT token for
client_assertion
contains the following information:
Header: {"typ": "JWT", "alg": "RS256"}
Payload: { "iss": "0-AECA", "exp": 1469474193, "aud": "oracle/iot/oauth2/token"}
MIICWwIBAAKBgQDdlatRjRjogo3WojgGHFHYLugdUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQsHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5Do2kQ+X5xK9cipRgEKwIDAQABAoGAD+onAtVye4ic7VR7V50DF9bOnwRwNXrARcDhq9LWNRrRGElESYYTQ6EbatXS3MCyjjX2eMhu/aF5YhXBwkppwxg+EOmXeh+MzL7Zh284OuPbkglAaGhV9bb6/5CpuGb1esyPbYW+Ty2PC0GSZfIXkXs76jXAu9TOBvD0ybc2YlkCQQDywg2R/7t3Q2OE2+yo382CLJdrlSLVROWKwb4tb2PjhY4XAwV8d1vy0RenxTB+K5Mu57uVSTHtrMK0GAtFr833AkEA6avx20OHo61Yela/4k5kQDtjEf1N0LfI+BcWZtxsS3jDM3i1Hp0KSu5rsCPb8acJo5RO26gGVrfAsDcIXKC+bQJAZZ2XIpsitLyPpuiMOvBbzPavd4gY6Z8KWrfYzJoI/Q9FuBo6rKwl4BFoToD7WIUS+hpkagwWiz+6zLoX1dbOZwJACmH5fSSjAkLRi54PKJ8TFUeOP15h9sQzydI8zJU+upvDEKZsZc/UhT/SySDOxQ4G/523Y0sz/OZtSWcol/UMgQJALesy++GdvoIDLfJX5GBQpuFgFenRiRDabxrE9MNUZ2aPFaFp+DyAe+b4nDwuJaW2LURbr8AEZga7oQj0uYxcYw==
The signature is obtained by signing the "Header.Payload" by the SHA256withRSA
algorithm using the device's private key. This algorithm is typically used for getting a message token.
The JSON Web Token Builder site might help you construct a valid JWT token.
curl -X POST -H 'Accept:application/json' -H 'Content-Type: application/x-www-form-urlencoded' --data "grant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJBQUFBQUFRMEZSMEEtQ0UiLCJhdWQiOiJvcmFjbGUvaW90L29hdXRoMi90b2tlbiIsImV4cCI6MTQ2OTQ3NDE5M30.oDiGi13Xw1ZJJ3iMDOSpZLN1NNfTVF8wJuWy2sMzcKKVIUbULeFCUoyd8SZiJBXMQDd4n_dRtF5vq7or3kGGiKOiWkS3V-r1qqqL0-o02Hh2tQ4AOHvwMRbEQOGE3lA7doNRd9sr7BR5zQGu4yahCh5581Q_4B5gV-ZN65gbdt4&scope=" http://iotserver/iot/api/v2/oauth2/token
Example of Response Header
status: 200 OK
Content-Type: application/json
Example of Response Body
{
"expires_in":3600000,
"token_type":"Bearer",
"access_token":"6074b571c671fe3cd548a8e668042187"
}