OTA API Authorization Developer Guide

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

https://apis.zebra.com/v1/user/token

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


Method Post

Header

Authorization Format: Basic Base64encoded(client id: Client secret)

yes Base64encoded for client id: Client secret


yes

Request Body

scope Default values zuid%20openid

No User profile value to be returned client application

Response details


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).

https://apis.zebra.com/v1/user/device_authorization

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


POST /v1/user/device_authorization HTTP/1.1


Authorization: Basic

dldQWEZiMkZGNW9YeW45RU1mSDhCeWJ3VGZGblVYckE6SUcwczlIZzV4MGZoamFCdA

==



{

"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


Method


Zebra Savanna API

URL

uri /v1/user/device_authorization

404 {"error_description":"Not Found" , "error":"Not Found"}

Header

Authorization





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


https://apis.zebra.com/v1/user/token

Zebra Savanna API


Method Post

Header

Authorization

Mandatory

yes Client authentication credentials Format: Basic Base64encoded(client id:Cleint secret)


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


Description

Response Body



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





dldQWEZiMkZGNW9YeW45RU1mSDhCeWJ3VGZGblVYckE6SUcwczlIZzV4MGZoamFCdA

==


Zebra Savanna API

grant_type=urn:ietf:params:oauth:grant-

type:device_code&device_code=YFlDH7h3W8xpz04rSCWcD1Ofc4XLeLbqOka3XaJnRU


{

"access_token": "uhf1MXlyI7ZJ8rfrCLpveVuM1Hc0",

"refresh_token": "MqVHsbR64uONjy8MfANBtqWvaUyk2Y5iEU6T0SrS7s",


"sub": "***.com",

"zuid": "de002fa6-1aa1-4b6c-b8ff-94875047d637"

}

Error details


Method


URL


Header

Authorization





Request Body

grant_type




400 (bad request)


device_code Device code missing 400 (bad request)

{"error_description":"Device code not set" , "error":"bad request"}

Zebra Savanna API


{"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.

https://apis.zebra.com/v1/

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



Method Post yes

Header


yes Base64 encoded for client id: Client secret


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

https://api.zebra.com/v1/user/token

Zebra Savanna API

Response details


Description

Response Body



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





dldQWEZiMkZGNW9YeW45RU1mSDhCeWJ3VGZGblVYckE6SUcwczlIZzV4MGZoamFCdA==


grant_type=refresh_token&refresh_token=MqVHsbR64uONjy8MfANBtqWvaUyk2Y5iEU6T0SrS

7s


{

"access_token": "nH2DfurBD7s4Rk14REEAnLM2Ts5x",

"refresh_token": "34xNOqLll19rAstOE3qWa7SSMSxoOa3VIcWN2GZJ",


"sub": "***@**.com",

}

Error details

Zebra Savanna API


Method


URL


Header

Authorization





Request Body

grant_type




400 (bad request)


refresh_token

Refresh token missing 400 (bad request)

{"error_description":"Refresh token not set" , "error":"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


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




dldQWEZiMkZGNW9YeW45RU1mSDhCeWJ3VGZGblVYckE6SUcwczlIZzV4MGZoamFCdA==

Zebra Savanna API


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

https://tools.ietf.org/html/rfc6749#section-3.1.2

OTA API Authorization Developer Guide

Documents

Transcript of OTA API Authorization Developer Guide