GPII OAuth 2 Guide
Contents
Introduction
We are adding access control to the Cloud-Based Flow Manger to secure access to user preferences. We are implementing the security using the OAuth 2.0 Authorization Framework. Please see the "OAuth 2.0 Resources" section below for a list of resources.
Supported OAuth 2.0 Grant Types
The OAuth 2.0 specification provides for a number of different usage scenarios. GPII supports a custom grant types "Resource Owner GPII Key Grant" that is used for GPII app installation to access user settings from GPII Cloud.
Resource Owner GPII Key Grant
Resource Owner GPII Key Grant is a custom grant created based upon The OAuth 2.0 Resource Owner Password Credentials Grant. This grant is used when requesting user settings from GPII Cloud. A typical use case is, a GPII app installed on a user's computer requests user settings associated with a GPII key from GPII Cloud.
Work Flow
Requesting a user's setting from GPII Cloud follows these steps:
- The OAuth client, such as a GPII app, authenticates with the authorization server and requests an access token
- Use the access token to request user settings
Step 1: Request an access token
POST <authorization-server>/access_token
Parameters
Send these parameters in the POST body using the application/x-www-form-urlencoded Content-Type.
| Name | Description |
|---|---|
grant_type
|
The value must be set to "password". |
client_id
|
The OAuth2 client id. |
client_secret
|
The OAuth2 client_secret. Confidential shared secret, used to verify the identity of the OAuth2 client.
|
username
|
The GPII key. |
password
|
Any string. Note: The GPII authorization server uses the oauth2orize library to implement the support of the OAuth2 authorization grants. The value of the `password` field can NOT be left empty due to the requirement of this library: |
Response
The /access_token endpoint will respond with a JSON document of this form:
{
"access_token": "<access_token>",
"expiresIn": <number_of_seconds_to_expire>,
"token_type": "Bearer"
}
For example:
{
"access_token": "8ea3457bf283db5d34ea5a4079fa36b2",
"expiresIn": 3600,
"token_type": "Bearer"
}
Step 2.1: Use the access token to request user settings
Note: The implementation of this step is in progress.
With the access token, we can now request user settings.
GET /:gpiiKey/settings/:device
Provide the access token using an "Authorization" header:
Authorization: Bearer <access_token>
For example:
Authorization: Bearer 8ea3457bf283db5d34ea5a4079fa36b2
Response
The /settings endpoint will respond with a JSON document of lifecycle instructions. An example of the return payload can be found here.
Step 2.2: Use the access token to save user preferences
Note: The implementation of this step is in progress.
With the access token, we can now request user settings.
PUT /:gpiiKey/settings
Provide the access token using an "Authorization" header:
Authorization: Bearer <access_token>
For example:
Authorization: Bearer 8ea3457bf283db5d34ea5a4079fa36b2
Response
The /settings endpoint will respond with a JSON document of whether the save is successful.
For example:
{
"gpiiKey": "li",
"messgae": "Successfully updated."
}
Solution Registry entries
| Name | Description |
|---|---|
OAuth2 client id
|
Used as the OAuth 2.0 client_id.
|
OAuth2 client name
|
The client name used in the user interface. |
client_secret
|
Confidential shared secret, used to verify the identity of the OAuth2 client. |
