ota api authorization developer guide
TRANSCRIPT
Zebra Savanna API
OTA API Authorization
Developer Guide
Scope: OAuth 2 integration
Revision No. 1.0
Date: 03/11/2019
Printed versions may be used as reference documents only.
© Copyright Zebra Inc. ALL RIGHTS RESERVED
Zebra Savanna API
Contents 1 Introduction ....................................................................................................................................... 3
2 Overview ........................................................................................................................................... 3
2.1 OAuth 2.0 Overview ................................................................................................................... 3
2.2 Responsibilities .......................................................................................................................... 3
2.2.1 Client Application’s Developer Responsibility ..................................................................... 3
3 Get authorization ............................................................................................................................... 4
3.1 Authorization code grant type ................................................................................................... 4
3.1.1 Step 1: Redirect user to authentication URL ....................................................................... 5
3.1.2 Step 2: Authorization and redirect back to client’s callback URL ........................................ 5
3.1.3 Step 3: Get access token..................................................................................................... 6
3.2 Device flow grant type ............................................................................................................... 8
3.2.1 Step 1: Get user code, device code, and verification URL ................................................... 9
3.2.2 Step 2: Display user code and verification URL ................................................................. 11
3.2.3 Step 3: Authorize the client .............................................................................................. 11
3.2.4 Step 3: Get access token................................................................................................... 11
4 Use of Authorization ........................................................................................................................ 14
5 Refresh authorization ...................................................................................................................... 15
5.1 Refresh the access token.......................................................................................................... 15
6 Revoke authorization ....................................................................................................................... 17
7 Reference ........................................................................................................................................ 19
Zebra Savanna API
1 Introduction This document provides the client application an overview of Zebra’s SSO based 3-legged OAuth 2.0
protocol. This document provides an overview of the processes a client application developer
needs to consider when integrating with Zebra’s OAuth 2.0 protocol.
2 Overview
2.1 OAuth 2.0 Overview
The OAuth 2.0 protocol uses a number of actors to achieve the main tasks of getting, validating,
and using an access token.
Access tokens are the identifier for authorization to a client issued by Authorization Server. The access token has a shorter lifetime and fewer permissions than the user. The actors in OAuth flow are
• User (Resource owner)
• Client Application (Application which consumes Zebra APIs)
• Authorization Server
• Resource Server (Zebra APIs)
2.2 Responsibilities
2.2.1 Client Application’s Developer Responsibility
• Get authorization from a user to call Zebra APIs
• Use the authorization in subsequent calls to Zebra protected APIs
• Refresh the authorization if expired using refresh tokens
Zebra Savanna API
Refresh tokens are credentials used to obtain new access tokens. Refresh tokens are issued
to the client by the authorization server and are used to obtain a new access token when
the current access token becomes invalid or expires
• Revoke the authorization.
3 Get authorization
Authorization to the client application is granted by the authorization server by means of the access
token. The client application can get the access token by Authorization server by two ways, which
are as following
• Authorization code grant type
• Device flow grant type
3.1 Authorization code grant type
Authorization grant is a client redirect based flow. Details explained the steps below.
Pre-requisites
• Register client’s callback URL at Zebra SSO by working with your Zebra liaison. The URL
needs to be provided by the client application. This URL is used to redirect the user to back
client application with the authorization code.
o URL Should be absolute in nature
o Query parameters should be in an encoded format
• The client application developer needs to register with Zebra’s developer portal and obtain
the valid, authorized client credentials i.e. client id and client secret
• Form authentication URL.
Prod Zebra SSO’s authorization endpoint URL:
https://pi.zebra.com/as/authorization.oauth2?response_type=code&client_id=AuthCode_a
pigee&redirect_uri=<Client’s callback URL in encoded format>
Zebra Savanna API
The Client's call URL must be absolute and URL encoded.
3.1.1 Step 1: Redirect user to authentication URL
The flow starts from the client application redirecting the user to the Zebra SSO’s
authorization endpoint URL (mentioned above) via a web browser.
3.1.2 Step 2: Authorization and redirect back to client’s callback URL
The user must authorize the client application by logging in and approving the
permission to share the displayed profile information with the client application. On
approval, an intermediate code generated and returned back to the client application
via a browser based on the registered client’s callback URL.
Zebra Savanna API
An authorization code is provided to the client application by the end of this step. The
authorization code will be a random string with expire time set to 60 seconds.
Attributes Content type Expire time
Response Body
code random string, send as query parameter 60 seconds
3.1.3 Step 3: Get access token
Lastly, the client will swap this code for an OAuth access token via API call.
Request details
URL: https://apis.zebra.com/v1/user/token
Attributes Validation Required description
Method Post
Header
Authorization Basic Base64encoded(client id: Client secret)
yes
Client authentication credentials.
Client application developers are required to obtain these Zebra’s developer portal and embed in the cleint application
Content-Type application/x-www-form-URL encoded
yes
Request Body
grant_type Value MUST be set to "authorization_code"
yes
redirect_uri MUST be identical to redirect URL included in step 1
yes Call back URL of the cleint application, must be registered with the authorization server.
code Not expired yes The authorization code received from the authorization server in step 2
Response details
Attributes Content type Expire time Description
Response Body
access_token random string 2 hours credentials used to access protected resources
refresh_token random string Unlimited credentials used to new access, refresh tokens
Zebra Savanna API
expires_in Seconds expire time for the access token
sub user's login id Zebra Internal users: Core ID Zebra external users: email id
zuid user zuid zuid for external, empty for internal users
Sample Postman Request
POST /v1/user/token HTTP/1.1
Host: apis.zebra.com
Authorization: Basic XXXXXXXXXXXXXXXXXX
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&redirect_uri=http://dummyredirecturl.zebra.com&cod
e=KHeV2CZFm1MqIFDP3TuC2lljtkBDXKDcfioAAAAD
Sample Postman Response
{
"access_token": "aSW3p2nkcybke2XgTQHlovXMZ39B",
"refresh_token": "xYmcdv0e3J2S73UdugHsWOfpw6D9j2vLPdJVGhJrRN",
"expires_in": "1799",
"sub": "***",
}
“generate access token” in attached postman export.
Error details
Error Description Error code Error Message
Method
Method post 405 {"error_description": "Method Not Allowed","error": "Method Not Allowed"}
URL
uri /v1/user/token 404 {"error_description":"Not Found" , "error":"Not Found"}
Header
Zebra Savanna API
Authorization
Authorization is missing 400(bad request)
{"error_description":"authorization set in-correctly", "error":"bad request"}
Invalid Authorization 401 (Unauthorized)
Invalid client identifier {0}
Request Body
grant_type
grant type is missing 400 (bad request)
{"error_description":"Invalid request URI" , "error":"bad request"}
Must be one of the following values: authorization_code refresh_token urn:ietf:params:oauth:grant-type:device_code
400 (bad request)
{"error_description":"Invalid grant_type" , "error":"bad request"}
code
Authorization code missing 400 (bad request)
{"error_description":"Authrization code not set." , "error":"bad request"}
Invalid code 400 (bad request)
{"error_description": "Authorization code is invalid or expired.","error": "invalid_grant"}
redirect_uri
Redirect url missing 400(bad request)
{"error_description":"Redirect URL not set" , "error":"bad request"}
Invalid URL 400(bad request)
{"error_description": "redirect_uri value must be identical to the value included in the authorization request.","error": "invalid_grant"}
3.2 Device flow grant type
Pre-requisites
Zebra Savanna API
• The client application developer needs to register with Zebra’s developer portal and
obtain valid, authorized client credentials i.e. client id and client secret.
3.2.1 Step 1: Get user code, device code, and verification URL
The client application initiates the process by triggering an API request to obtain user
code, device code, and verification URL from authorization server.
Request details
URL: https://apis.zebra.com/v1/user/device_authorization
Attributes Validation Required description
Method Post
Header
Authorization Format: Basic Base64encoded(client id: Client secret)
yes Base64encoded for client id: Client secret
Content-Type application/x-www-form-URL encoded
yes
Request Body
scope Default values zuid%20openid
No User profile value to be returned client application
Response details
Attributes Content type Expire time
Description
Response Body
user_code random string The end-user verification code
device_code random string Unlimited
An identifier assigned by the authorization server to client instance. Will be used in later steps
interval Seconds 5 the time interval to authorization check loop
verification_uri
The end-user verification URI on the authorization server. The end users required to manually type it into their user-agent (browser).
Zebra Savanna API
verification_uri_complete A verification URI that includes the "user_code", designed for non-textual transmission.
expires_in 600
The lifetime in seconds of the "device_code" and
"user_code".
Default 600
Sample Postman Request
POST /v1/user/device_authorization HTTP/1.1
Host: apis.zebra.com
Authorization: Basic
dldQWEZiMkZGNW9YeW45RU1mSDhCeWJ3VGZGblVYckE6SUcwczlIZzV4MGZoamFCdA
==
Content-Type: application/x-www-form-urlencoded
Sample Postman Response
{
"user_code": "YK9R-3GQX",
"device_code": "xMD7ZU3t9VpEj0F3l7rvQjpOY13pgpSCK5wbfqKKDy",
"interval": 5,
"verification_uri_complete": "https://test-
pi.zebra.com/as/user_authz.oauth2?user_code=YK9R-3GQX",
"verification_uri": "https://pi.zebra.com/as/user_authz.oauth2",
"expires_in": 600
}
Error details
Error Description Error code Error Message
Method
Method post 405 {"error_description": "Method Not Allowed","error": "Method Not Allowed"}
Zebra Savanna API
URL
uri /v1/user/device_authorization
404 {"error_description":"Not Found" , "error":"Not Found"}
Header
Authorization
Authorization is missing 400(bad request)
{"error_description":"authorization set in-correctly", "error":"bad request"}
Invalid Authorization 401 (Unauthorized)
Invalid client identifier {0}
3.2.2 Step 2: Display user code and verification URL
After receiving a successful Authorization Response, the client application must display
or communicate the "user_code" and the "verification_uri" to the end user, instructing
them to visit the URI in a user agent on a secondary device (for example, in a browser
on their mobile phone), and enter the user code.
3.2.3 Step 3: Authorize the client
User must follow the login using zebra’s credentials and authorize the client application.
3.2.4 Step 3: Get access token
After displaying instructions to the user, the client application must start reaching to the
authorization server to get the status on authorization by the user. The client expected
to repeatedly check in a polling fashion, based on the error code in the response and
interval. Once the user authorizes, the authorization server responds back with an
access token for the authorization check request.
Request details
URL: https://apis.zebra.com/v1/user/token
Zebra Savanna API
Attributes Validation Required description
Method Post
Header
Authorization
Mandatory
yes Client authentication credentials Format: Basic Base64encoded(client id:Cleint secret)
Content-Type application/x-www-form-URL encoded
yes
Request Body
grant_type value must be urn:ietf:params:oauth:grant-type:device_code
yes
device_code must be the values received in step 1 and not expired
yes Client to be authorized
Device code received in step 1
Response details
Attributes Content type Expire time
Description
Response Body
access_token random string 2 hours credentials used to access protected resources
refresh_token random string Unlimited credentials used to new access, refresh tokens
expires_in Seconds expire time for access token
sub user's login id Zebra Internal users: Core ID
Zebra external users: email id
zuid user zuid zuid for external, empty for internal users
Sample Postman Request
POST /v1/user/token HTTP/1.1
Host: apis.zebra.com
Authorization: Basic
dldQWEZiMkZGNW9YeW45RU1mSDhCeWJ3VGZGblVYckE6SUcwczlIZzV4MGZoamFCdA
==
Content-Type: application/x-www-form-urlencoded
Zebra Savanna API
grant_type=urn:ietf:params:oauth:grant-
type:device_code&device_code=YFlDH7h3W8xpz04rSCWcD1Ofc4XLeLbqOka3XaJnRU
Sample Postman Response
{
"access_token": "uhf1MXlyI7ZJ8rfrCLpveVuM1Hc0",
"refresh_token": "MqVHsbR64uONjy8MfANBtqWvaUyk2Y5iEU6T0SrS7s",
"expires_in": "1799",
"sub": "***.com",
"zuid": "de002fa6-1aa1-4b6c-b8ff-94875047d637"
}
Error details
Error Description Error code Error Message
Method
Method post 405 {"error_description": "Method Not Allowed","error": "Method Not Allowed"}
URL
uri /v1/user/token 404 {"error_description":"Not Found" , "error":"Not Found"}
Header
Authorization
Authorization is missing 400(bad request)
{"error_description":"authorization set in-correctly", "error":"bad request"}
Invalid Authorization 401 (Unauthorized)
Invalid client identifier {0}
Request Body
grant_type
grant type is missing 400 (bad request)
{"error_description":"Invalid request URI" , "error":"bad request"}
Must be one of the following values: authorization_code refresh_token urn:ietf:params:oauth:grant-type:device_code
400 (bad request)
{"error_description":"Invalid grant_type" , "error":"bad request"}
device_code Device code missing 400 (bad request)
{"error_description":"Device code not set" , "error":"bad request"}
Zebra Savanna API
Invalid code 400 (bad request)
{"error_description": "Device code not found, expired or invalid.","error": "invalid_grant"}
4 Use of Authorization
An access token can be used as an authorization token to access Zebra protected APIs. To use an
access token to access a protected resource, the access token must be passed as a Bearer
authorization credential in HTTP Authorization header.
Endpoint URL (assume): https://apis.zebra.com/v1/ota-api/artifacts/
Apigee gateway will validate the access token, on being valid, request will be proxied to backend
Zebra APIs.
The API developer needs to configure the access token validation endpoint at the respective
apigee’s API proxy.
Zebra Savanna API
5 Refresh authorization
Once access token is expired, the client application is required to get the new access token and new
refresh token using existing refresh token so that it can make Zebra API calls uninterruptedly
Pre-requisites
• The client application developer needs to register with Zebra’s developer portal and
obtain valid, authorized client credentials i.e. client id and client secret.
• Refresh token must be valid.
• The client must be authorized to refresh the tokens
5.1 Refresh the access token
The client application must make the following API call to authorization server’ token endpoint
to refresh the access token
Request details
URL: https://apis.zebra.com/v1/user/token
Attributes Validation Required description
Method Post yes
Header
Authorization Format: Basic Base64encoded(client id: Client secret)
yes Base64 encoded for client id: Client secret
Content-Type application/x-www-form-URL encoded
yes
Request Body
grant_type should be refresh_token yes grant type
refresh_token yes The token that the client wants for new access and refresh token
Zebra Savanna API
Response details
Attributes Content type Expire time
Description
Response Body
access_token random string 2 hours credentials used to access protected resources
refresh_token random string Unlimited credentials used to new access, refresh tokens
expires_in Seconds expire time for the access token
Sub user's login id Zebra Internal users: Core ID
Zebra external users: email id
Zuid user zuid zuid for external, empty for internal users
Sample Postman Request
POST /v1/user/token HTTP/1.1
Host: apis.zebra.com
Authorization: Basic
dldQWEZiMkZGNW9YeW45RU1mSDhCeWJ3VGZGblVYckE6SUcwczlIZzV4MGZoamFCdA==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=MqVHsbR64uONjy8MfANBtqWvaUyk2Y5iEU6T0SrS
7s
Sample Postman Response
{
"access_token": "nH2DfurBD7s4Rk14REEAnLM2Ts5x",
"refresh_token": "34xNOqLll19rAstOE3qWa7SSMSxoOa3VIcWN2GZJ",
"expires_in": "1799",
"sub": "***@**.com",
}
Error details
Zebra Savanna API
Error Description Error code Error Message
Method
Method post 405 {"error_description": "Method Not Allowed","error": "Method Not Allowed"}
URL
uri /v1/user/token 404 {"error_description":"Not Found" , "error":"Not Found"}
Header
Authorization
Authorization is missing 400(bad request)
{"error_description":"authorization set in-correctly", "error":"bad request"}
Invalid Authorization 401 (Unauthorized)
Invalid client identifier {0}
Request Body
grant_type
grant type is missing 400 (bad request)
{"error_description":"Invalid request URI" , "error":"bad request"}
Must be one of the following values: authorization_code refresh_token urn:ietf:params:oauth:grant-type:device_code
400 (bad request)
{"error_description":"Invalid grant_type" , "error":"bad request"}
refresh_token
Refresh token missing 400 (bad request)
{"error_description":"Refresh token not set" , "error":"bad request"}
Invalid code 400 (bad request)
{"error_description": "unknown, invalid, or expired refresh token","error": "invalid_grant"}
6 Revoke authorization
Zebra Savanna API
When a user wants to revoke their authorization over a client application or when client applications are
uninstalled, the client applications need to invalidate the refresh (or both tokens) by triggering an API
call to the authorization server.
Following are the revoke API details.
Attributes Validation Required Sample value
Method Post
Header
Authorization Format: Basic Base64encoded(client id: Client secret)
yes Base64 encoded for client id: Client secret
Content-Type application/x-www-form-urlencoded
yes
Request Body
token The refresh token that the client wants to revoke.
Yes The token that the client wants to revoke.
token_type_hint Optional, can be either No
A hint about the type of token submitted for revocation. Following values are supported: access_token or refresh_token
Sample request
POST /v1/user/token HTTP/1.1
Host: apis.zebra.com
Authorization: Basic
dldQWEZiMkZGNW9YeW45RU1mSDhCeWJ3VGZGblVYckE6SUcwczlIZzV4MGZoamFCdA==
Zebra Savanna API
Content-Type: application/x-www-form-urlencoded
token=CRxNR69pKfQZd1h3SRTR7FRCrQFkgItudqv2MhFt6q&token_type_hint=refresh_token
Sample response
{
"Message": "Access and Refresh Token has been revoked successfully"
}
7 Reference
• Authorization code grant type: https://tools.ietf.org/html/rfc6749#section-3.1.2
• Device flow grant type: https://tools.ietf.org/html/draft-ietf-oauth-device-flow-14
• Revoke token: https://tools.ietf.org/html/rfc7009