目录

Verifying an ID Token

To ensure secure network access, use the TLS 1.2 protocol and supported cipher suites. If your app server accesses Account Kit using TLS 1.0, TLS 1.1, or unsupported cipher suites, the connection may fail.

For details about TLS 1.2 and supported cipher suites, please refer to TLS Protocol and Cipher Suites.

Functions

Your app server calls this API on the Account Kit server to verify an ID token and parse the ID token. It is used for debugging only.

Use Cases

Constraints

Prototype

Request Parameters

[h2]Request Header

Parameter Mandatory Type Description
Content-Type Yes String

Content type. The value is application/x-www-form-urlencoded.

NOTE

The request body parameters must follow the format defined in the request header. Otherwise, the request may fail. For details on how to pass these parameters, please refer to Sample Code.

[h2]Request Body

Parameter Mandatory Type Description
id_token Yes String ID token obtained by an app.

Request Example

Send a POST request. Example:

POST /oauth2/v3/tokeninfo HTTP/1.1
Host:oauth-login.cloud.huawei.com
Content-Type: application/x-www-form-urlencoded

id_token=<id_token>

Response Parameters

[h2]Response Header

Parameter Mandatory Type Description
Content-Type Yes String Content type. The value is application/json.

[h2]Response Body

If the API is successfully called, the response body is as follows.

Parameter Mandatory Type Description
typ Yes String ID token format. The value is always JWT.
alg Yes String

ID token signing algorithm.

- PS256

- RS256
kid Yes String ID of the public-private key pair used for signature verification. The value contains a maximum of 256 characters.

If the API fails to be called, the response body is as follows.

Parameter Type Description
error int Error code. For details, please refer to HTTP Response Codes.
sub_error int Sub-error code. For details, please refer to HTTP Response Codes.
error_description String Error description.

ID Token Parsing

Some parameters are returned only when certain scopes are passed for ID token generation. Check the tables below for the relationships between parameters and scopes.

If the openid scope is passed in the request, parameters in the following table are returned.

Parameter Mandatory Type Description
iss Yes String The value is always https://accounts.huawei.com.
sub Yes String UnionID of a user. For details about the format requirements, please refer to Formats of OpenID and UnionID.
aud Yes String Client ID of the app that receives an ID token.
exp Yes Long Time when an ID token expires (10 digits).
iat Yes Long Time when an ID token is generated (10 digits).
at_hash Yes String Access token hash value.
azp Yes String Client ID of the app that generates an ID token.
openid Yes String OpenID of a user. For details about the format requirements, please refer to Formats of OpenID and UnionID.
nonce No String Random value for replay attack prevention. For details, please refer to the description of the nonce field in LoginWithHuaweiIDRequest or AuthorizationWithHuaweiIDRequest.

If the profile scope is passed in the request, parameters in the following table are returned.

Parameter Mandatory Type Description
picture No String

User avatar link.

NOTE

The original avatar link becomes invalid immediately after the user updates the avatar. To ensure that the avatar can be properly displayed, it is advised to download and save the avatar before using it. This prevents service processes from being affected due to invalid avatar links.
display_name No String Nickname of a HUAWEI ID. If this parameter is not set, the anonymized email address or mobile number is displayed.
nickname No String Nickname of a HUAWEI ID.

If the quickLoginAnonymousPhone scope is passed in the request, the parameter in the following table is returned.

Parameter Mandatory Type Description
anonymized_login_mobile_number No String Anonymized mobile number bound to a HUAWEI ID. For details, please refer to Signing In with HUAWEI ID Through Just One Tap (Obtaining the Mobile Number, UnionID, and OpenID).

If the email scope is passed in the request, parameters in the following table are returned.

Parameter Mandatory Type Description
email_verified No Boolean

Indicates whether a user's email address has been verified.

- true: yes

- false: no

As an email address is not a required field for a HUAWEI ID, the response may not include this parameter.
email No String Email address. As an email address is not a required field for a HUAWEI ID, the response may not include this parameter.

Response Example

[h2]Request Success

HTTP/1.1 200 OK
Content-Type: application/json

{
    "at_hash": "Dx5WUwU*****L-SKuAvWUg",
    "sub": "AQAxrB1HNA*****n-IfWRSUVq2M7xU",
    "kid": "6a2880c5d6a88c*****88eb680e05197d5bebd*****7b71757fc1b9530809ca",
    "iss": "https://accounts.huawei.com",
    "typ": "JWT",
    "display_name": "Jack",
    "nickname": "Jack",
    "aud": "30*****33",
    "azp": "30*****33",
    "exp": 1563823909,
    "iat": 1563820309,
    "alg": "PS256",
    "nonce": "default",
    "openid": "AQAxrBzThFv*****lv9tV_4rMCc"
}

[h2]Request Failure

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "sub_error": 14004,
    "error_description": "jwk not found error",
    "error": 1400
}

Sample Code

The Java sample code is as follows. Before running it, set up the environment for the sample code. (Place this sample code and the CallUtils utility class in the same directory. If not, manually add the corresponding import statement to the sample code.)

import com.alibaba.fastjson2.JSONObject;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.message.BasicNameValuePair;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

/**
 * Verify an ID Token.
 */
public class IDTokenAPIDemo {
    public static void main(String[] args) throws IOException {
        // URL of the API for verifying an ID token.
        String url = "https://oauth-login.cloud.huawei.com/oauth2/v3/tokeninfo";
        // Replace it with the ID token you obtained.
        String idToken = "<ID Token>";
        JSONObject result = getDetailByIDToken(url, idToken);
        // Parse the result to obtain kid.
        String kid = result.getString("kid");
        // Parse the result to obtain typ.
        String typ = result.getString("typ");
        // Parse the result to obtain alg.
        String alg = result.getString("alg");
        // Parse the result to obtain iss.
        String iss = result.getString("iss");
        // Parse the result to obtain sub.
        String sub = result.getString("sub");
        // Parse the result to obtain aud.
        String aud = result.getString("aud");
        // Parse the result to obtain exp.
        Long exp = result.getLong("exp");
        // Parse the result to obtain iat.
        Long iat = result.getLong("iat");
        // Parse the result to obtain at_hash.
        String atHash = result.getString("at_hash");
        // Parse the result to obtain azp.
        String azp = result.getString("azp");
        // Parse the result to obtain openid.
        String openid = result.getString("openid");
        // Parse the result to obtain nonce.
        String nonce = result.getString("nonce");
    }

    private static JSONObject getDetailByIDToken(String url, String idToken) throws IOException {
        HttpPost httpPost = new HttpPost(url);
        List<NameValuePair> request = new ArrayList<>();
        request.add(new BasicNameValuePair("id_token", idToken));
        httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded");
        httpPost.setEntity(new UrlEncodedFormEntity(request));
        return CallUtils.toJsonObject(CallUtils.remoteCallOAuth(httpPost));
    }
}

HTTP Response Codes

HTTP Response Code Description Solution
200 Success. -
400 Parameter error. Further locate the error based on the relevant error code and sub-error code.
403 No access permission. Check the network environment configuration to see if the access is blocked by the caller's network security policy. If the error persists, submit a ticket online.
404 Service not found. Ensure that the request URI is correct.
405 Unsupported HTTP request method. Ensure that the method for the HTTP request complies with the API specifications.
500 Internal service error. Submit a ticket online.
502 Connection error. This typically occurs when network connectivity is unstable. Try again later. If the error persists, submit a ticket online.
503 System rate limiting triggered. Rate limiting has been triggered by the system. Try again later.
504 Connection timed out. This typically occurs when network connectivity is unstable. Try again later. If the error persists, submit a ticket online.
590 Internal service error. Submit a ticket online.
Error Code Sub-error Code Description Solution
1203 100305 The header obtained from the parsed ID token is not in JSON format. The value format of id_token is incorrect or its value is forged. Ensure that its value is the original one returned by the HUAWEI ID.
1203 100306 The payload obtained from the parsed ID token is not in JSON format. The value format of id_token is incorrect or its value is forged. Ensure that its value is the original one returned by the HUAWEI ID.
1203 150021 Failed to parse the header of the ID token. The value format of id_token is incorrect or its value is forged. Ensure that its value is the original one returned by the HUAWEI ID.
1203 150022 Failed to parse the payload of the ID token. The value format of id_token is incorrect or its value is forged. Ensure that its value is the original one returned by the HUAWEI ID.
1203 150023 Failed to parse the signature of the ID token. The value format of id_token is incorrect or its value is forged. Ensure that its value is the original one returned by the HUAWEI ID.
1400 14004 The JWT public key is not found based on the value of kid. Submit a ticket online.
1500 15003 Invalid ID token. The value format of id_token is incorrect or its value is forged. Ensure that its value is the original one returned by the HUAWEI ID.
1500 15004 Failed to verify the ID token. The value format of id_token is incorrect or its value is forged. Ensure that its value is the original one returned by the HUAWEI ID.
1500 15005 Failed to verify the issuer of the ID token. Ensure that the value of id_token is the original one returned by the HUAWEI ID.
1500 15006 The ID token has expired. Obtain a new ID token.
1500 15007 The id_token parameter is left empty. Pass a valid value for the id_token parameter according to the parameter specifications.
1500 15008 The ID token format is incorrect. Ensure that the value of id_token matches the regular expression ^[0-9a-zA-Z_\-\.]+$.
1203 500 Internal system error. Record the error code and submit a ticket online.
1203 1203 Unknown system error. Record the error code and submit a ticket online.