Infinity/Evolution Open API OAuth 2.0 Specification

Infinity/Evolution Open API OAuth 2.0 Specification

Version 1.5 August 15, 2016

? 2016 Carrier Corporation ? Proprietary Information.

Contents

1 OAuth 2.0 Overview ................................................................................................... 3 1.1 Key Terms ........................................................................................................... 4

2 Using OAuth 2.0 to Access the Infinity/Evolution Open API ...................................... 6 2.1 Obtain OAuth 2.0 Credentials From Carrier ........................................................ 6 2.2 Obtain an Access Token From the Carrier Authorization Server ........................ 6 2.3 Send the Access Token to an API....................................................................... 7 2.4 Refresh the Access Token (If Necessary) ........................................................... 7

3 "Authorization Code" Flow Message Specifications................................................... 8 3.1 Authentication to the Authorization Server .......................................................... 8 3.2 Authorization Request ......................................................................................... 9 3.3 Available Scopes ............................................................................................... 10 3.4 Authorization Response .................................................................................... 11 3.5 Authorization Error Response ........................................................................... 12 3.6 Access Token Request ..................................................................................... 13 3.7 Access Token Response................................................................................... 14 3.8 Access Token Error Response.......................................................................... 15

4 "Client Credential" Flow Message Specifications..................................................... 16 4.1 Authentication to the Authorization Server ........................................................ 17 4.2 Available Scopes ............................................................................................... 17 4.3 Access Token Request ..................................................................................... 17 4.4 Access Token Response................................................................................... 18 4.5 Access Token Error Response.......................................................................... 19

5 Invoking a Business Service .................................................................................... 20 6 Refreshing Access Tokens ...................................................................................... 21

6.1 Refresh Access Token Request ........................................................................ 21 6.2 Refresh Access Token Response ..................................................................... 22 6.3 Refresh Access Token Error Response ............................................................ 23

? 2016 Carrier Corporation ? Proprietary Information.

1 OAuth 2.0 Overview

Authorization of access to the Infinity/Evolution Open API utilizes the OAuth 2.0 security authorization protocol, which was designed to grant limited client access to a resource. OAuth 2.0 is an Internet Engineering Task Force (IETF) standard defined by RFC 6749. Complete documentation on the standard can be found at . Within the OAuth2 specification, there are four different authorization grant types that entail different overall authorization flows. "Authorization Code" and "Client Credential Grant" are the two supported methods for accessing the Infinity/Evolution Open API. The "Authorization Code" flow must be used when an individual user, who is registered in MyInfinity, is authorizing an application to access resources served by the Carrier Open API. The "Client Credential Grant" grant is a simplified authorization flow that should be used when a utility company application is accessing resources served by the Infinity/Evolution Open API and cannot be directly associated with an individual user registered in MyInfinity. OAuth2 authorization is facilitated using the Hypertext Transfer Protocol, using Transport Layer Security (TLS) to encrypt the data connection (i.e. the HTTPS scheme). All interaction with the authorization server is via relatively simple REST web services. OAuth2 clients can be built by using HTTP GET and POST methods to access authorization URL's. When accessing services with the HTTP GET method, parameters must be supplied as URL query parameters. When accessing services using the HTTP POST method, parameters must be supplied using the "application/xwww-form-urlencoded" format. The authorization server provides a numerical HTTP response code, as well as a message body in JavaScript Object Notation (JSON).

? 2016 Carrier Corporation ? Proprietary Information.

1.1 Key Terms

The OAuth2 specification uses the following key terms:

? Resource Owner: The owner of a resource to be accessed by an application. The owner could be the user accessing a system. For example, in the use case of an application that needs to retrieve the e-mail address and phone number of a user, the user might be considered the resource owner.

? Client: The application that authenticates and gains authorization with the authorization server, and subsequently uses this authorization to access a resource.

? Authorization Server: The server that authenticates and authorizes a client to access requested resources. Within this document, the authorization server is MyInfinity ().

? Resource Server: The server that provides a resource to clients, provided that the authorization to access the resources can be validated with the authorization server. Within this document, the resource server is the Open API ().

? Authorization Endpoint: The endpoint used by the client to obtain authorization from the resource owner via user-agent redirection. The client must make a GET request to the authorization endpoint by adding parameters to the query component of the authorization endpoint URI using the "application/x-www-formurlencoded" format.

? Token Endpoint: The endpoint used by the client to exchange an authorization grant for an access token, typically with client authentication. The client must make a POST request to the token endpoint by sending the parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8.

? Redirect Endpoint: The client endpoint used by the authorization server to return responses containing authorization credentials to the client via the resource owner user-agent.

? Authorization Code: A code requested by a client from the authorization server. The code has a short lifespan and must be redeemed for an access token in order to gain authorization to a resource. Authorization codes are only used when an individual user that is registered in MyInfinityTouch is authorizing an application to access private resources on the Carrier Resource Server.

? Access Token: A tokenized string requested by a client from the authorization server. The token is passed to the resource server, which validates the token in order to grant access. The token has a limited lifespan, but can be refreshed using the refresh token.

? Refresh Token: A tokenized string provided to a client by the authorization server when an access token is requested. An access token can be renewed at

? 2016 Carrier Corporation ? Proprietary Information.

any time by using the refresh token. However, a refresh token cannot be used to access a resource. ? Scope: A space-delimited set of permissions that the application is requesting or an access token permits. ? HTTP Basic Authentication: A client must authenticate with the authorization server by providing its ID and "secret key" which is synonymous with a password. The client simply concatenates these two parameters, separated by a colon, Base64 encodes the concatenation and provides the result in the HTTP "Authorization" header. Example: Authorization: Basic tGzv3JOkF0XG5Qx2TlKWIA

? 2016 Carrier Corporation ? Proprietary Information.

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download