中文简体    English

Single Sign-On (SSO) API Interface Api

Version history:

Copyright statement: © 2019 IvyIot All Rights Reserved. It is
strictly forbidden to use all or part of this document for printing or
making electronic documents without the written authorization of IvyIot.

The information contained in this document is for use only by
IvyIot personnel, authorized users of the device, and persons
authorized by IvyIot, and it is strictly forbidden to use it for
other purposes. Information in this document is subject to change
without notice.

Trademark Notice: IvyIot ™ and the IvyIot logo are registered
trademarks and service marks of IvyIot. Other product, brand, or
service names are trademarks or service marks of their respective
owners. Reproduction, display, or use of its trademark or service mark
without the written permission of IvyIot is strictly prohibited.

References: IvyIot is not responsible for providing all documents
referenced with the device in this document. IWay reserves the right to
determine which documents are provided with the products and services.

1 Introduction

1.1 Document Introduction

This document introduces the docking process and detailed interface
docking details of the Ivy SSO authentication platform, so that
merchants can integrate and dock to achieve landing on the Ivy platform.

1.2 Applicable people

This document is written for those who need to access the IVY platform
for products, development, and testing.

2. Access instructions

2.1 Certification requirements

2.1.1 Server requirements

• The server must be accessible from the Internet.
• To connect with our foreign business, you need an international
  network or a server located abroad.
• For security reasons, the server needs to implement the https
  protocol and configure the corresponding domain.
• The server time needs to ensure that the real-time synchronization
  is accurate.

2.1.2 necessary configuration

• A. Client id and secret clientId and clientSecret are necessary
  options for the IVY platform to use for server authentication during
  the SSO login process and need to be generated and provided by the
  business.
• B. Implementing the token verification and obtaining user
  information interface During the docking process, the IVY platform
  needs to verify the token provided by the merchant, so the merchant
  needs to implement the token verification interface and return user
  information. In processing the callback for updating and deleting
  user information, the merchant user information needs to be
  confirmed, so the merchant needs to implement a user information
  interface via uuid (for details of the specific interface, see the
  authentication and authentication section).

2.2 Interactive Process

2.2.1 Basic description

• A. Merchants use our token to log in to our company through the App
  and get refreshToken and accessToken.
• B. If the accessToken expires, you can use refreshToken to refresh
  to obtain a new accessToken.
• C. If the refreshToken in B expires, you need to re-initiate the
  login process of A.
• D. The merchant uses the callback method to update or delete the
  user data information in our system.

2.2.2 Timing diagram

A. Merchants log in to our company

\

\

B. Merchant refreshToken expiration process

\

\

C. Merchants modify user information

\

\

D. Merchant deletes user information

\

\

3. Docking Details

3.1 API specifications

• Now call the following sample interface in GET mode to explain the
  process of connecting to the IVY API:
  https://api.ivyiot.com/sso/user_callback?operation=UPDATE&uuid=204242f98b4247998a1e52496331e6a

3.1.1 Determine parameters

S1. Determine basic parameters

• A. Example of determining the request method: GET
• B. Example of obtaining the unix timestamp of the current system:
  1555931103
• C. Example of determining the currently used API docking version:
  1.0, the current API version is 1.0
• D. Example of determining the url: / sso / user_callback
• E. Parameter sorting: All parameters need to be sorted by parameter
  name first, and then all parameters are connected with “&” using
  “parm = parameter value” Example: operation = UPDATE &
  uuid = 204242f98b4247998a1e52496331e6a0
• F. Client clientId and clientSecret

S2. Creating a signed string

• To obtain the string to be encrypted, use the request method + “\
  n” + Url + “\ n” + sorted parameters + “\ n” + unix timestamp
  Example: GET \ n / sso / user_callback \ noperation = UPDATE &
  uuid = 204242f98b4247998a1e52496331e6a0 \ n1549266882

S3. Create a signature

• Encryption key: clientSecret + unixtimestamp
• Encryption method: use key to HMAC-SHA256 encryption the string
  generated in 2 to get sign =
  92e508b14cf405d6508930bdf38ad2f439054c3a43281860287d3c3ad8b7eee9

3.1.2 Create Request

• A. Determine the request method, url and parameters are as above
• B. Generate http request header x-client-time Client request created
  linux timestamp x-version Request version number x-client-Id Client
  id sign 3.1.1 signature created in

3.1.3 Response status code

• The network status code 200 normally returns a 401 error. If there
  is no response, the authentication fails. If there is a response,
  please handle the error code. [For specific error code handling,
  refer to the description in the interface details]

3.2 Merchant Client Process

• S1. Get Request Information

  • A. Example of the request method: GET / POST
  • B. Example of getting url: / sso / user_callback
  • C. Get request parameters, sort them by parm, and
    concatenate them into strings Example: operation = UPDATE & uuid
    = 204242f98b4247998a1e52496331e6a0
  • D. Example of the requested unix time: 1555931103

• S2. Request authentication

  • A. Determine whether the request timed out. The maximum timeout
    period is 15 seconds.
  • B. Refer to step 3 in 3.3.1 to calculate the signature sign and
    compare it with the signature in the request header.
  • S3. Process the business and return according to the specified
    result (refer to the interface details for the return of each
    interface).

3.3 IVY interface implementation

3.3.1 Login with token

Interface description:

• This API is called by the application and logs in to the IVY service
  through a token.
• Originator: Mobile application / other end-user application
• Recipient: IVY Services

Request URL:

• https://{HOST}/ sso / authorize_by_token

Request method:

• POST

Request header:

• Refer to 3.1.2 “Generating HTTP Request Headers”.

Request parameters:

Response status code:

• 200 request succeeded
• 401 Request failed

Return example:

Returns when correct:

Response Code： 200
Response Body：
{
    "accessToken":"8e34108f0dfe4efeac29701a1ae16fe5",
    "refreshToken":"67fd1a923d104ac792c1bf69532a1e70",
    "expiresIn":86400
}

Returns on failure:

Response Code： 401
Response Body：
{
    "failureDetails":"partner authorization denied",
    "errorCode":"OP0051",
    "expiresIn":0
}

Return parameter description:

Error code description:

• no

3.3.2 refresh accessToken interface

Interface description:

• This API is called by the application and refreshes the accessToken
  interface through refreshToken.
• Originator: Mobile application / other end-user application
• Recipient: IVY Services

Request URL:

• https://{HOST}/sso/refresh_token

Request method:

• POST

Request header:

• Refer to 3.1.2 “Generating HTTP Request Headers”.

Request parameters:

Response status code:

• 200 request succeeded
• 401 Request failed

Return example:

Returns when correct:

Response Code： 200
Response Body：
{
    "accessToken":"8e34108f0dfe4efeac29701a1ae16fe5",
    "refreshToken":"67fd1a923d104ac792c1bf69532a1e70",
    "expiresIn":86400
}

Returns on failure:

Response Code： 401
Response Body：
{
    "failureDetails":"refreshtoken expired",
    "errorCode":"030051",
    "expiresIn":0
}

Return parameter description:

Error code description:

3.3.3 User Information Callback Interface

Interface description:

• This API is called by the application, and the callback informs the
  IVY platform to update or delete shadow account information.
• Originator: Mobile application / other end-user application
• Recipient: IVY Services

Request URL:

• https://{HOST}/sso/user_callback

Request method:

• POST

Request header:

• Refer to 3.1.2 “Generating HTTP Request Headers”.

Request parameters:

Response status code:

• 200 request succeeded
• 401 Request failed

Return example:

Returns when correct:

Response Code： 200
Response Body：
{
    "errorCode":"",
    "failureDetails":""
}

Returns on failure:

Response Code： 401
Response Body：
{
    "failureDetails":"refreshtoken expired",
    "errorCode":"030051"
}

Return parameter description:

Error code description:

• no

3.4 Merchant Implementation Interface

3.4.1 Verifying Token Validity

Interface description:

• The IVY service uses this API to verify whether the token is valid
  and obtain user information.
• Started by: IVY Services
• Recipient: Merchant server

Request URL:

• Custom (but need to give to our company, reference:/idp/is_valid_token)

Request method:

• GET

Request header:

• no

Request parameters:

Response status code:

• 200 request succeeded
• 401 Request failed

Return example:

Returns when correct:

Response Code： 200
Response Body：
{
    "errorCode":"",
    "failureDetails":"",
    "user":{
        "uuid":"9314839c623048e88afdcd0e9802e2aa",
        "username":"9314839c623048e88afdcd0e9802e2aa@ivyiot.io",
        "name":"233671",
        "nickname":"",
        "phone":"",
        "country":""
    }
}

Returns on failure:

Response Code： 401
Response Body：
{
    "failureDetails":"token is invalid",
    "errorCode":"xxxxxx"
}

Return parameter description:

Error code description:

• no

3.4.2 Querying User Information

Interface description:

• The IVY service uses this API to query user information using uuid.
• Started by: IVY Services
• Recipient: Merchant server

Request URL:

• Custom (but need to give to our company, reference: / idp /
  get_user_profile)

Request method:

• GET

Request header:

• no

Request parameters:

Response status code:

• 200 request succeeded
• 401 Request failed

Return example:

Returns when correct:

Response Code： 200
Response Body：
{
    "errorCode":"",
    "failureDetails":"",
    "user":{
        "uuid":"9314839c623048e88afdcd0e9802e2aa",
        "username":"9314839c623048e88afdcd0e9802e2aa@ivyiot.io",
        "name":"233671",
        "nickname":"",
        "phone":"",
        "country":""
    }
}

Returns on failure:

Response Code： 401
Response Body：
{
    "failureDetails":"user profile not exists",
    "errorCode":"xxxxxx"
}

Return parameter description:

Error code description:

• no

4 Code examples

4.1 Java code example

• A. Request verification

// 校验时间x-client-time与服务器时间间隔不能超过15秒
String clientTime = headers.get(IvyConstant.KEY_HEADER_CLIENT_TIME);
if (!isClientTimeValid(clientTime)) {
    return false;
}

// 校验sign是否匹配
String partnerSign = headers.get(IvyConstant.KEY_HEADER_SIGN);
String sign = IvyAuthUtil.getPartnerSign(uri, httpMethod, clientTime, params);
if (StringUtils.isEmpty(partnerSign) || !partnerSign.equals(sign)) {
    log.warn("IvyHttpInterceptor.handler not passed. sign is invalid. partnerSign={}, sign={}", partnerSign, sign);
    return false;
}

• B. Calculate sign

String canonicalUri = getCanonicalUri(uri);
String canonicalQueryString = getCanonicalQueryString(params);

// 计算toSign
String toSign = httpVerb + "\n" + canonicalUri + "\n" + canonicalQueryString + "\n" + time;

// 计算signature
String signature = OpenEncrypt.ivySha256HMAC(secret + time, toSign, AylaHttpClient.CHARSET_UTF8);

return signature;