How to implement account management in your proprietary app based on a user account system-阿里云帮助中心

Built-in account system

The built-in account system is a service that IoT Platform provides. To use this system, you can integrate the Account and User software development kit (SDK) into your client. The Account and User SDK provides a logon page with features such as account registration, logon, logoff, password reset, language switching, profile picture modification, nickname modification, and account closure. You can also customize the UI of this page. For more information, see Account and User SDK for Android and Account and User SDK for iOS.

Note

If your app is for release outside China, we recommend including the following content.

Mailbox registration: Allow users to register with an email address. This method is common for users outside China.
Multi-language switching: The platform supports multiple languages, and more are continuously added.
Account closure: To comply with strict regulations outside China, such as the General Data Protection Regulation (GDPR), your app must provide a feature to close user accounts. When an account is closed, all associated user data must be deleted.

Your own account system

If you have your own account system, you can integrate it with IoT Platform to enable features such as device attachment, device sharing, and device message push. IoT Platform does not store user information from your account system, which protects user privacy.

The integration of your own account system uses the OAuth 2.0 protocol. OAuth 2.0 is an open standard for access delegation. For more information, see the RFC definition reference. Follow these steps to configure and develop the integration.

Go to the User Account configuration page for your proprietary app.
Select Your own account system and click Settings.
Configure your account system and click Confirm to save the configuration.

You must provide the URLs for Access/Refresh URL and GetuserinfoURL.

Develop your account system.

Follow the flowchart below to complete the development.

流程图

The detailed flow is described as follows.

Implement the app logon process. Retrieve the AuthCode for the current user from the app authentication service and pass it to the SDK. For information about how to use the SDK, see "Third-party proprietary accounts" in Account and User SDK (Android) and Account and User SDK (iOS).

Note
The app requests an AuthCode from the app authentication service. You are responsible for implementing this service. This service typically handles authentication, logon, issuing an AuthCode, validating an AuthCode, and issuing and validating tokens. For a typical implementation, you can use secure random number generation to create a random string. Associate the requested client_id with the logon account. This ensures that the AuthCode used to request an access_token in step 2 can be used only once.

IoT Platform sends an HTTP POST request to your app authentication service to retrieve a token.

The request contains the client_id, AuthCode, and client_secret parameters. The response must include the result_code, access_token, and refresh_token parameters.

Note

For all HTTP requests related to IoT Platform account integration, the Content-Type of the request and response must be application/json.

Request to exchange an AuthCode for an access_token

This is a standard OAuth 2.0 token exchange request. The following example assumes that Access/Refresh URL is set to https://test.net/api/users/oauth/token.

POST /api/users/oauth/token?grant_type=authorization_code&client_id=testxxx&client_secret=testxxxxx&code=test222224tD2fVtexxxxojFZL6&redirect_uri=none HTTP/1.1
Host: test.net
Content-Type: application/x-www-form-urlencoded

Request field	Type	Description
grant_type	String	The authorization type. The value is fixed to the string `authorization_code`.
client_id	String	The AppKey issued by IoT Platform.
client_secret	String	The AppSecret issued by IoT Platform.
code	String	The AuthCode returned in step 1.

The following code provides an example of a successful response from your app authentication service to IoT Platform.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "result_code":"0",
   "openid":"OPENID",
   "access_token":"2YotnxxxxMWpAA",
   "refresh_token":"tGzvxxxx2TlKWIA"
}

Response field	Type	Description
result_code	String	0: Success 100000: The client_id or client_secret is invalid. 100002: Failed to exchange the AuthCode for an access_token. 100007: Invalid authorization code. 110000: General system error code.
openid	String	The unique identifier of the user.
access_token	String	The authorization token.
refresh_token	String	The token used to get a new access_token. This parameter is required for automatic authorization renewal.
expires_in	String	The validity period of the access_token in seconds.

Request to refresh an access_token

POST /api/users/oauth/token?grant_type=refresh_token&client_id=testxx&client_secret=test2222&refresh_token=test222testaaaL6 HTTP/1.1
Host: test.net
Content-Type: application/x-www-form-urlencoded

Request field	Type	Description
grant_type	String	The authorization type. The value is fixed to the string `refresh_token`.
client_id	String	The AppKey issued by IoT Platform.
client_secret	String	The AppSecret issued by IoT Platform.
refresh_token	String	The refresh_token that was returned when the access_token was obtained.

The following code provides an example of a successful response.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "result_code":"0",
  "openid":" OPENID",
  "access_token":"2YotnFxxxxsicMWpAA",
  "refresh_token":"tGzv3Jxxxx2TlKWIA"
}

Response field	Type	Description
result_code	String	0: Success 100000: The client_id or client_secret is invalid. 100003: The refresh_token has expired or is invalid. 110000: General system error code.
openid	String	The unique identifier of the user.
access_token	String	The authorization token.
refresh_token	String	The token used to get a new access_token. This parameter is required for automatic authorization renewal.

Using the access_token obtained in the previous step, IoT Platform retrieves user information from the app user service based on the OpenId.

The app user service is the account management service within your proprietary app's account system. It typically manages basic account registration and account information. You must implement an HTTP request that uses an OAuth token for authentication to retrieve basic user information.

The example URL is https://thrid.com/sns/userinfo. The request method is POST.

The following is an example request.

POST /api/users/oauth/userinfo?access_token=testaaaatest222a779537c6687c3 HTTP/1.1
Host: testxx.net
Content-Type: application/x-www-form-urlencoded

Request field	Type	Description
access_token	String	The access_token obtained in step 2.
openid	String	The unique identifier of the user. This parameter is optional. If you want to support voice control integration with Google Assistant and Amazon Alexa, you must set this parameter as optional.

The following shows a sample response.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "result_code": "0",
   "message": "Success",
   "openid":" OPENID", 
   "nick_name": "NICKNAME",
   "avatar_url": "image.com/xxxx.png",
   "gender": "1"
}

Response field	Type	Description
result_code	String	0: Success 100000: The client_id or client_secret is invalid. 100001: The access_token has expired. 100002: Failed to exchange the AuthCode for an access_token. 100003: The refresh_token has expired or is invalid. 100004: The access_token is invalid because the user changed the password or revoked authorization. 100005: The access_token is illegal. 100006: The OpenId is invalid. 100007: Invalid authorization code. 110000: General system error code.
message	String	A description of the response result.
openid	String	The unique identifier of the user.
nick_name	String	The user's nickname.
avatar_url	String	The URL of the profile picture.
gender	String	The user's gender. Valid values: 0: Unknown 1: Male 2: Female

Global user access for your own account system

IoT Platform provides unified global account access. If you have multiple data centers, users are connected to the nearest data center. This ensures the fastest response times and helps meet compliance requirements. Your account system can be configured with only one endpoint. The endpoint is the domain name in the token URL and getUserInfo URL that you configure for app account access. If your account system has multiple data centers worldwide, you can use the following methods to support them.

When the regional authentication service generates an authCode, add a flag to indicate the data center.
Add the flag to the AuthCode, and to the access_token and refresh_token that are generated during the AuthCode exchange.
Use a unified endpoint for request forwarding.
The following flowchart shows the process.
The following methods are recommended for implementing unified request forwarding.
- Use a smart CDN and build your own NGINX reverse proxy cluster.
- Use a smart CDN and route traffic through API Gateway to Alibaba Cloud Function Compute.
- Use Alibaba Cloud edge services, such as EdgeRoutine.

Get the URL and encrypted signature for profile picture uploads

If your proprietary app allows end users to upload profile pictures, follow these steps during development.

Call the Get the URL and encrypted signature for profile picture uploads API operation to retrieve the upload URL, signature, and other parameters.
After the app retrieves the upload URL, signature, and other parameters, it uploads the profile picture using the POST method. For more information, see PostObject.
When you upload the picture, set the x-oss-forbid-overwrite parameter in the header to false. Otherwise, the upload may fail.
Concatenate the URL.
Concatenate the host and dir parameters from the API response in Step 1 to form the profile picture URL. Use the following format: "https://" + host + "/" + dir.
Update the image URL using the Account Service API.

Development notes for app registration and logon

When you develop user accounts for your proprietary app, note the country selection requirements for app registration and logon, as shown in the following table.

Operation	API Level 9 and later	API Level 8 and earlier
Register app	Country selection required	Country selection required
Log on to app	Country selection not required	Select the country used for registration

The country selected during account registration cannot be changed after the account is registered. Devices attached to this account connect to the data center in the region that corresponds to the selected country. To switch data center regions, you must close the account, register a new account in the new country, and then re-attach the original devices.

Therefore, when you develop the business logic for app registration and logon, you can refer to the implementation on the Cloud Intelligence App page. When country selection is required, you must clearly inform end users (consumers) of the impact of their choice. The selected country determines the account's location and the server region to which attached devices connect. This helps prevent consumers from randomly selecting a country, which can result in a poor device connection experience.