Connecting to Cesium ion with OAuth2
Cesium ion uses the Authorization Code Grant flow for accessing a user’s account using OAuth2.
Register your application
Once logged into Cesium ion, click on your username in the upper right corner to go to your settings.
Under Developer Settings
, click Add Application
Enter the name of your application that will be displayed to the user and the redirect URI. The redirect URI must be passed to the Code Authorization
and Token Exchange
API calls and will be the location the user is redirected to once they authorize your application.
Code authorization
You will make a request for a code
that will prompt the user for permissions. Once permission is granted we will redirect the user back to you with the code
.
Request
This request should be made by redirecting the user to this page. It will prompt the user to log in to Cesium ion and ask for their permission to give you access. For native applications, this request should be made through a browser and not an embedded web view.
GET https://cesium.com/ion/oauth
Parameters:
-
response_type
(Required) Must always have the valuecode
since we only use one flow type. -
client_id
(Required) The client ID that was assigned to your application when you registered it. -
redirect_uri
(Required) The URI that a user will be redirected to once they authorize your application. This must match the URI provided when you registered your application. -
scope
(Required) A space separted list of requested scopes. Possible scopes are:- assets:list : List the metadata for all assets available to the account. - assets:read : Read metadata and access the tiled data for individual assets in the account. - assets:write : Create, modify, and delete assets in the account.
-
state
A unique string that will be sent back to theredirect_uri
. Used to protect against cross-site request forgery attacks. This is not required but strongly recommended.
The following 2 parameters are used if you implement the PKCE extension. This is recommended to increase security. If you use the extension, then both are required.
-
code_challenge
A Base64 URL encoded SHA256 hash of thecode_verifier
that you will pass with the token exchange request. -
code_challenge_method
Must beS256
Response
Once they user has granted permission, Cesium ion will redirect the user to the redirect_uri
you specified in the request.
GET [redirect_uri]
Parameters:
-
redirect_uri
The URI you passed during the request. This much match the Redirect URI of the registered application. -
code
This is a code that you will use during the token exchange step. -
state
This is the exact string you passed during the request. If it is different do not proceed to the token exchange step.
Token exchange
Once you have the code
you can exchange it for an access_token
, which you can then use that to access the user’s account.
Request
POST https://api.cesium.com/oauth/token
Parameters:
-
grant_type
(Required) Must always have the valueauthorization_code
. -
client_id
(Required) The client ID that was assigned to your application when you registered it. -
code
(Required) This is a code that you were provided during the authorization step. -
redirect_uri
(Required) The URI that a user was redirected to during the authorization step. This must match the URI provided when you registered your application.
The following parameter is required if you used the PKCE extension in the authorization step.
code_verifier
The string whose hash value was passed to the authorization step in thecode_challenge
parameter.
Response
The format of the response depends on the Accept
header used during the request.
If application/json
is an acceptable response you receive:
{
"access_token": "[access_token]",
"token_type": "bearer"
}
If application/xml
is an acceptable response you recieve:
<OAuth>
<access_token>[access_token]</access_token>
<token_type>bearer</token_type>
</OAuth>
Otherwise you recieve:
access_token=[access_token]&token_type=bearer
access_token
The token that can be used to access the Cesium ion API.
Example
Send
https://cesium.com/ion/oauth?response_type=code&client_id=1456&redirect_uri=https%3A%2F%2Fmy.website.com&scope=asset:read%20asset:list&state=a576f975g00d&code_challenge=bKE9UspwyIPg8LsQHkJaiehiTeUdstI5JZOvaoQRgJA&code_challenge_method=S256
Redirect (once user approves access):
https://my.website.com?code=6907&state=a576f975g00d
Send
https://api.cesium.com/oauth/token
With Post data and accept header application/json
{
"grant_type": "authorization_code",
"client_id": 1456,
"code": 6907,
"redirect_uri": "https://my.website.com",
"code_verifier": "abc123"
}
Response:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiMSIsImlhdCI6MTUxNjIzOTAyMn0.fZSuqRyznO9h4U2qdPLrGNj1lQ4rR-4vkrr0dy7ryCc",
"token_type": "bearer"
}
Computing the code challenge
Here is a code sample that can be used in your application to generate the code_challenge
for the PKCE extension.
const crypto = require('crypto');
const codeVerifier = 'abc123'; // This code should be randomly generated
const hash = crypto.createHash('sha256').update(codeVerifier).digest();
const codeChallenge = hash.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');