Authenticating APIs

Scenario

You can configure OAuth to manage third-party access authentication using the OAuth 2.0 protocol. Before calling an API of Huawei Cloud Astro Zero, a third-party system needs to be authenticated and registered with Huawei Cloud Astro Zero to obtain credentials such as the access client ID and key. Once authenticated, the third-party system can call the API.

Huawei Cloud Astro Zero supports authentication with client credentials or authorization codes for OAuth authentication.

• Client Credential

  The access token obtained through this mode can be used for authentication when an API is called. Set access-token in the request header.

  Figure 1 Client credential
  
• Authorization Code

  The access token obtained through this mode is only used to authenticate requests for obtaining user information. Set Authorization in the request header.

  Each authentication key has specific usage. You are advised to create an authentication key for each third-party system.

  Figure 2 Authorization code
  

Access Authentication with Client Credentials

1. Go to the Huawei Cloud Astro Zero console.
2. On the homepage, click Access Homepage. The Huawei Cloud Astro Zero development page is displayed.
3. Click and choose Environments > Environment Configuration.
4. Create a machine user account.
   Machine users can log in to the Huawei Cloud Astro Zero only in OAuth client mode.

   1. In the navigation pane, choose User Security > Users. Then click New.
   2. Set User Type to Machine User, set other user information, and click the save button.
      Figure 3 Creating a machine user
      

5. In the navigation pane, choose Integrated Connection > OAuth and click New.
6. Set the authorization type to Client Credential, set other parameters by referring to Table 1, and click Save.
   • Each authentication key has specific usage. You are advised to create an authentication key for each third-party system.
   • The user associated with OAuth must have the permission to access related APIs. Otherwise, the callback fails due to permission issues.

     Table 1 Parameters

     Parameter	Description
     Name	Name of the third-party system to be connected. The naming requirements are as follows: Value: 1–64 characters. Start with a letter and can contain only letters, digits, and underscores (_). Do not end with an underscore (_).
     Authentication Type	Authorization type for the third-party system to access Astro Zero through OAuth 2.0. The default value is Client Credential. Retain the default value.
     User	Select the machine user created in 4. After the third-party authentication is successful, the same permissions as those of the user can be obtained.
     Login IP Address Range	Specifies whether to specify the login IP address range. If this parameter is selected, only IP addresses in the specified range can access Huawei Cloud Astro Zero.
     Start	Start IP address. It must be a valid IPv4 address and cannot exceed the end IP address. This parameter is displayed only after Login IP Address Range is selected.
     End	End IP address. It must be a valid IPv4 address and must be equal to or greater than the start IP address. This parameter is displayed only after Login IP Address Range is selected.
     Description	Description of access authentication. Value: 1–255 characters.

7. On the OAuth page, click in the row that contains the target authentication key, download the key file to a local directory, and obtain the client ID and client secret in this file.
   The name of the key file downloaded to the local PC is Authentication name.txt. The file contains the following parameters:

   • username: user selected in step 6.
   • client_id: client ID for authentication.
   • client_secret: client secret for authentication.

8. Call the API /baas/auth/v1.0/oauth2/token to obtain an access token based on the client ID and secret.

   Table 2 Basic API information

   API	Path	Protocol	API Method
   token	/baas/auth/v1.0/oauth2/token	HTTPS	POST

   Table 3 Request parameters

   Parameter	Type	Mandatory (M)/Optional (O)	Location	Description	Value
   grant_type	String	M	Body	Authorization mode, which is the value of grant_type in OAuth 2.0. Options: client_credentials authorization_code	Set this parameter to client_credentials, indicating the client mode.
   client_id	String	M	Body	Client ID for authentication.	Set this parameter to the value obtained in 7.
   client_secret	String	M	Body	Authentication key.	Set this parameter to the value obtained in 7.
   redirect_url	String	O	Body	Redirection URL.	Configure the value based on site requirements.
   locale	String	O	Body	Language.	en_US

   Example:

   Use this curl request to simulate API invoking: curl -i -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=client_credentials&client_id=App ID&client_secret=App secret' https://Astro Zero domain name/baas/auth/v1.0/oauth2/token

   Response:

   {
       "access_token": "ACCESS_TOKEN",
       "expires_in": 7200,
       "token_type": "Bearer"
   }

   Record the obtained access token, which will be used by the third party to access the service API.

9. Service API called by a third-party system. The following uses the custom API queryEquipments (elevator device query API) as an example.
   1. Call the following RESTful API queryEquipments.

      https://Domain name/service/Namespace__Elevator/1.0.1/queryEquipments

      Replace Domain name with the development-state domain name provided externally, and replace service/Namespace__Elevator/1.0.1/queryEquipments with the URL of the custom API.

   2. (Required for CSRF verification of public APIs) To obtain the value of csrf-token, call the API https://Huawei Cloud Astro Zero domain name/u-route/baas/sys/v1.0/csrf/get. The returned result is a CSRF token.

      Specify the access-token in the request header, that is, the value obtained in 8.

   3. Add "access-token":"ACCESS_TOKEN", "Content-Type":"application/json", and "csrf-token":"result value in the previous step" to the request header.
   4. Write the input parameters of the API in the request body.

      {
          "equipmentSn": "001"
      }

   5. If the call is successful, the output result is returned.

      {
        "interviewId": "002N000000MJ77KcFGwC",
        "outputs": {
          "Equipments": [
            {
              "Namespace__equipmentBrand__CST": null,
              "Namespace__equipmentModel__CST": null,
              "Namespace__equipmentSN__CST": "9996660001",
              "Namespace__fullAddress__CST": "",
              "Namespace__installationDetailAddress__CST": null,
              "Namespace__installationSiteArea__CST": "",
              "Namespace__installationSiteCity__CST": "",
              "Namespace__installationSiteProvince__CST": "",
              "Namespace__latitude__CST": "",
              "Namespace__longitude__CST": "",
              "createdBy": "10gd000000MEGPaz7P16",
              "createdBy.__objectType": "User",
              "createdBy.name": "test",
              "createdDate": "2018-12-19 06:39:29",
              "currencyIsoCode": "",
              "custom": true,
              "equipmentSn__CST": "9996660001",
              "fullAddress__CST": "",
              "id": "c000000000MFhgYMQtmq",
              "installedPackage": null,
              "isLocked": false,
              "lastModifiedBy": "10gd000000MEGPaz7P16",
              "lastModifiedBy.__objectType": "User",
              "lastModifiedBy.name": "test",
              "lastModifiedDate": "2018-12-19 06:39:29",
              "latitude__CST": "",
              "longitude__CST": "",
              "name": "Example address 1",
              "owner": "10gd000000MEGPaz7P16",
              "owner.__objectType": "User",
              "owner.name": "test"
            },
            {
               "Namespace__equipmentBrand__CST": "",
              "Namespace__equipmentModel__CST": null,
              "Namespace__equipmentSN__CST": "3217890001",
              "Namespace__fullAddress__CST": "ssss",
              "Namespace__installationDetailAddress__CST": null,
              "Namespace__installationSiteArea__CST": null,
              "Namespace__installationSiteCity__CST": null,
              "Namespace__installationSiteProvince__CST": null,
              "Namespace__latitude__CST": null,
              "Namespace__longitude__CST": null,
              "createdBy": "10gd000000MEGPaz7P16",
              "createdBy.__objectType": "User",
              "createdBy.name": "test",
              "createdDate": "2018-12-18 12:49:46",
              "currencyIsoCode": "",
              "custom": true,
              "equipmentSN__CST": "3217890001",
              "fullAddress__CST": "ssss",
              "id": "c000000000METF70NiZk",
              "installedPackage": null,
              "isLocked": false,
              "lastModifiedBy": "10gd000000MEGPaz7P16",
              "lastModifiedBy.__objectType": "User",
              "lastModifiedBy.name": "test",
              "lastModifiedDate": "2018-12-21 07:34:06",
              "latitude__CST": "",
              "longitude__CST": "",
              "name": "Example address 2",
              "owner": "10gd000000MEGPaz7P16",
              "owner.__objectType": "User",
              "owner.name": "test"
            }
          ],
          "total": "2"
        }
      }

Access Authentication with an Authorization Code

1. Go to the Huawei Cloud Astro Zero console.
2. On the homepage, click Access Homepage. The Huawei Cloud Astro Zero development page is displayed.
3. Click and choose Environments > Environment Configuration.
4. In the navigation pane, choose Integrated Connection > OAuth and click New.
5. Set the authorization type to Authorization Code, set other parameters by referring to Table 4, and click Save.
   Each authentication key has specific usage. You are advised to create an authentication key for each third-party system.

   Table 4 Parameters

   Parameter	Description
   Name	Name of the third-party system to be connected. The naming requirements are as follows: Value: 1–59 characters. Start with a letter and can contain only letters, digits, and underscores (_). Do not end with an underscore (_).
   Authentication Type	Authorization type for the third-party system to access Astro Zero through OAuth 2.0. The default value is Client Credential. Select Authorization Code.
   Redirect URL	When a third-party system accesses the system, an authorization code is returned to the redirect URL. The third-party system will use the authorization code, client ID, and client secret to call an API to obtain an access token. The third-party system can use the access token to obtain the authorized user information.
   Description	Enter the authentication description as required. Value: 1–255 characters.

6. On the OAuth page, click in the row that contains the target authentication key, download the key file to a local directory, and obtain the client ID and client secret in this file.
   The key needs to be created only once. The key file contains the following parameters:

   • redirect_uri: redirection address set in 5.
   • client_id: client ID for authentication.
   • client_secret: client secret for authentication.

7. Obtain the authorization code.

   The API for the third-party system to obtain the authorization code is https://Domain name/baas/auth/v1.0/oauth2/authorize?response_type=code&client_id=Client ID&redirect_uri=Redirect URL. If the third-party system accepts the authorization, the authentication server redirects the browser to the redirect URL specified when the third-party system was registered, and the authorization code is contained, that is, redirect URL /?code=authorization code.

   If a message indicating that the URL cannot be accessed is displayed, check the following parameters:

   • Client ID: the client ID obtained in 6.
   • Redirect URL: the redirect URL set in 5.

8. Obtain the access token.
   The client uses the client ID, client secret, and authorization code to call the API https://Domain name/baas/auth/v1.0/oauth2/token to obtain the access token. The third-party system can use the access token to obtain the authorized user information.

   Table 5 Basic API information

   API	Path	Protocol	API Method
   token	https://Domain name/baas/auth/v1.0/oauth2/token	HTTPS	POST

   Table 6 Parameters

   Parameter	Type	Mandatory (M)/Optional (O)	Description	Value
   grant_type	String	M	Authorization mode, which is the value of grant_type in OAuth 2.0. Options: client_credentials authorization_code	Set this parameter to authorization_code.
   client_id	String	M	Client authentication ID.	Set this parameter to the value obtained in 6.
   client_secret	String	M	Client authentication key.	Set this parameter to the value obtained in 6.
   redirect_url	String	M	Redirect URL.	Set this parameter to the redirection address obtained in step 5.
   code	String	M	Authorization code.	Set this parameter to the value obtained in 7.
   locale	String	O	Language.	en_US

   Example:

   Use a curl request to simulate an API call: curl -i -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=authorization_code&client_id=Client ID&client_secret=Client secret&redirect_uri=Redirect URL&code=Authorization code' https://Domain name/baas/auth/v1.0/oauth2/token

   Response:

   {
       "access_token": "ACCESS_TOKEN",
       "expires_in": 7200,
       "refresh_token":"REFRESH_TOKEN",
       "token_type": "Bearer"
   }

9. (Optional) Refresh the access token.

   An access token has a short validity period. For example, the access token obtained in 8 is valid only for 7,200s (2 hours). When the access token expires, refresh it using a refresh token. The validity period of a refresh token is 30 days. When the refresh token expires, obtain a new access token.

   After obtaining a refresh token in 8, obtain the access token using the following URL:

   https://Domain name/baas/auth/v1.0/oauth2/token?grant_type=refresh_token&client_id=Client ID&client_secret=Client secret&refresh_token=REFRESH_TOKEN

10. Obtain information about authorized users.

    Request https://Domain name/u-route/baas/oauth/v1.0/userinfo using the GET method to obtain the authorized user information.

    {
      "resCode": "0",
      "resMsg": "Success",
      "result": {
        "usrname": "test",
        "alias": "",
        "email": "test@example.com",
        "aboutme": "",
        "company_name": "name01",
        "photo": "",
        "address": "",
        "phone": "188***8888",
        "country": "",
        "post_code": "",
        "province": "",
        "city": ""
      }
    }

Access Authentication with a Custom OAuth 2.0 Authorization Code

The preceding sections describe how to configure access authentication before a third-party system calls the Huawei Cloud Astro Zero service APIs. The Huawei Cloud Astro Zero service APIs can be called only after the authentication is successful. For applications developed in Huawei Cloud Astro Zero, you can also enable access authentication with a custom OAuth2 authorization code After authentication is configured for an application, only authenticated third-party systems can access the application.

1. Obtain the client ID and client secret by referring to 4 to 6 in Access Authentication with an Authorization Code.
2. Define a custom API on the application development page for third-party systems to obtain an authorization code.
3. The application calls the script API to check whether the client ID and redirect URL of the third-party client match those during registration access authentication.
   If yes, the Huawei Cloud Astro Zero application customizes an API to implement login redirection and authorization redirection. After the authorization is complete, the script API is called to obtain the authorization code and send the authorized user information to be displayed to the third-party system to Huawei Cloud Astro Zero through this API. Huawei Cloud Astro Zero returns a code. Finally, the application is redirected to redirect_url with the code.

   • Example API used to check whether the client_id and redirect_url of a third-party client are the same as those used for registration:

     // Here's your code.
     import * as oauth from 'oauth'
     let handle = oauth.getAuthorizeHandle()
     let clientDatas: oauth.clientDataFromApp = {
         redirect_uri: "http://10.26.30.68:14000/appauth/code",
         client_id: "bff4398905ee4a918722debec98b594c",
     }
     let pass = handle.checkURL(clientDatas)
     console.log(pass) //true
     if (pass){
     // Determine whether to allow the client to log in and perform redirection.
     // Determine whether to authorize the client and perform redirection.
     }

   • Example script API used to obtain an authorization code:

     // Here's your code.
     import * as oauth from 'oauth'
     let handle = oauth.getAuthorizeHandle()
      
      
     // The preceding steps are completed.
     let clientDatas: oauth.clientDataFromApp = {
           redirect_uri: "http://10.26.30.68:14000/appauth/code",
         client_id: "bff4398905ee4a918722debec98b594c",
     }
      
     let userInfo = {
         "name": "jack",
         "phone": "1256287222",
         "email": "example.com"
     } 
     let code = handle.getAuthCode(clientDatas, userInfo)
     console.log(code) //WEUcqXbeQDKUHxcn8til3Q

4. The third-party system receives the request, parses the code, and obtains the access token from the backend access API. The procedure is the same as that in 8.
5. After obtaining the access token, the third-party system uses it to call the API https://Domain name/u-route/baas/oauth/v1.0/third/userinfo (different from the API in 10) to obtain the authorized user information.
   Response example:

   {
       "resCode": "0",
       "resMsg": "Success",
       "result": {
           "email": "example.com",
           "name": "jack",
           "phone": "1256287222"
       }
   }