Obtaining a User Token Through Password Authentication

Function

This API is used to obtain a user token using the username and password. A token is an access credential issued to an IAM user to bear its identity and permissions. When calling the APIs of IAM or other cloud services, you can use this API to obtain a user token for authentication. However, you are advised to call APIs through AK/SK-based authentication to prevent API calling failures caused by invalid cached tokens.

The API can be called using either a global endpoint or a region-specific endpoint. For IAM endpoints, see Regions and Endpoints.

Before using this API, check the identity to be used to obtain the token.

Figure 1 Methods of obtaining tokens for different identities

• Obtaining a token as an IAM user

  Obtain a token based on the request parameters.

• Obtaining a token using a HUAWEI ID

  A HUAWEI ID cannot be directly used to obtain a token. Check whether your account is a HUAWEI ID by referring to How Do I Know What Account I Am Logged In With?

  To obtain a token, you need to create an IAM user, assign required permissions to the user, and use the IAM username and password to obtain a token.

• Obtaining a token using a Huawei Cloud account

  Obtain a token based on the request parameters.

• Obtaining a token as a third-party system user

  A third-party system user cannot directly obtain a token by using the username and password used for identity federation. Instead, you should go to the Huawei Cloud login page, click Forgot Password, and reset the password. Then you can use the new password to obtain a token.

Constraints

• The validity period of a token is 24 hours. Cache the token to prevent frequent API calling. Ensure that the token is valid before you use it. Using a token that will soon expire may cause API calling failures. Obtaining a new token does not affect the validity of the existing token.
• The token will become invalid within 30 minutes if any of the following occurs:
  • The IAM user is deleted or disabled.
  • The IAM user's password or access key is changed.
  • The IAM user's permissions are changed (for example, due to outstanding payments, OBT application approval, or permission modification).
• If The token must be updated is returned when a token is used to call a cloud service API, the token has expired. You need to obtain a new token.
• Whether a token can be tampered with: Token signature verification ensures that a token has not been tampered with by validating its signature.

Debugging

You can debug this API in API Explorer.

URI

POST /v3/auth/tokens

Request Parameters

Example Request

• Request for obtaining a token for an IAM user (username: IAMUser, password: IAMPassword, account name: IAMDomain, scope: project ap-southeast-1) without displaying catalog information in the response. You can obtain the IAM username and account name on the My Credentials page of the console. For details, see Obtaining Account, IAM User, Group, Project, Region, and Agency Information.

  POST https://iam.myhuaweicloud.com/v3/auth/tokens?nocatalog=true

  {
      "auth": {
          "identity": {
              "methods": [
                  "password"
              ],
              "password": {
                  "user": {
                      "domain": {
                          "name": "IAMDomain"        // Name of the account used to create the IAM user
                      },
                      "name": "IAMUser",             // IAM username
                      "password": "IAMPassword"      // IAM user password
                  }
              }
          },
          "scope": {
              "project": {
                  "name": "ap-southeast-1"               //Project name
              }
          }
      }
  }

• Request for obtaining a token for an IAM user (username: IAMUser, password: IAMPassword, account name: IAMDomain, scope: domain) You can obtain the IAM username and account name on the My Credentials page of the console. For details, see Obtaining Account, IAM User, Group, Project, Region, and Agency Information.

  POST https://iam.myhuaweicloud.com/v3/auth/tokens

  {
      "auth": {
          "identity": {
              "methods": [
                  "password"
              ],
              "password": {
                  "user": {
                      "domain": {
                          "name": "IAMDomain"        // Name of the account used to create the IAM user
                      },
                      "name": "IAMUser",             // IAM username
                      "password": "IAMPassword"      // IAM user password
                  }
              }
          },
          "scope": {
              "domain": {
                  "name": "IAMDomain"        // Name of the account used to create the IAM user
              }
          }
      }
  }

Response Parameters

Example Response

Status code: 201

The request is successful.

• Response to the request for obtaining a token for an IAM user (username: IAMUser, password: IAMPassword, account name: IAMDomain, scope: project ap-southeast-1) without displaying catalog information in the response

  Parameters in the response header (obtained token)
  X-Subject-Token:MIIatAYJKoZIhvcNAQcCoIIapTCCGqECAQExDTALB...

  Parameters in the response body
  {
      "token": {
          "catalog": [],
          "expires_at": "2020-01-04T09:05:22.701000Z",
          "issued_at": "2020-01-03T09:05:22.701000Z",
          "methods": [
              "password"
          ],
          "project": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "aa2d97d7e62c4b7da3ffdfc11551f...",
              "name": "ap-southeast-1"
          },
          "roles": [
              {
                  "id": "0",
                  "name": "te_admin"
              },
              {
                  "id": "0",
                  "name": "op_gated_Video_Campus"
              }
          ],
          "user": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "7116d09f88fa41908676fdd4b039e...",
              "name": "IAMUser",
              "password_expires_at": ""
          }
      }
  }

• Request for obtaining a token for an IAM user (username: IAMUser, password: IAMPassword, account name: IAMDomain, scope: domain)

  Parameters in the response header (obtained token)
  X-Subject-Token:MIIatAYJKoZIhvcNAQcCoIIapTCCGqECAQExDTALB...

  Parameters in the response body
  {
      "token": {
          "catalog": [
              {
                  "endpoints": [
                      {
                          "id": "33e1cbdd86d34e89a63cf8ad16a5f...",
                          "interface": "public",
                          "region": "*",
                          "region_id": "*",
                          "url": "https://iam.myhuaweicloud.com/v3.0"
                      }
                  ],
                  "id": "100a6a3477f1495286579b819d399...",
                  "name": "iam",
                  "type": "iam"
              },
              {
                  "endpoints": [
                      {
                          "id": "29319cf2052d4e94bcf438b55d143...",
                          "interface": "public",
                          "region": "*",
                          "region_id": "*",
                          "url": "https://bss.sample.domain.com/v1.0"
                      }
                  ],
                  "id": "c6db69fabbd549908adcb861c7e47...",
                  "name": "bssv1",
                  "type": "bssv1"
              }
          ],
          "domain": {
              "id": "d78cbac186b744899480f25bd022f...",
              "name": "IAMDomain"
          },
          "expires_at": "2020-01-04T09:08:49.965000Z",
          "issued_at": "2020-01-03T09:08:49.965000Z",
          "methods": [
              "password"
          ],
          "roles": [
              {
                  "id": "0",
                  "name": "te_admin"
              },
              {
                  "id": "0",
                  "name": "secu_admin"
              },
              {
                  "id": "0",
                  "name": "te_agency"
              }
          ],
          "user": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "7116d09f88fa41908676fdd4b039e...",
              "name": "IAMUser",
              "password_expires_at": ""
          }
      }
  }

Status code: 400

Invalid parameters. Check whether the request body complies with the JSON syntax.

{
    "error": {
        "code": 400,
        "message": "The request body is invalid",
        "title": "Bad Request"
    }
}

Status code: 401

Authentication failed.

• If you are a user of a third-party system, you cannot obtain a token by using the username and password that you use for federated identity authentication. Go to the Huawei Cloud login page, click Forgot Password, and reset the password.
• If your Huawei Cloud account has been upgraded to a HUAWEI ID, you cannot obtain a token using the HUAWEI ID. Instead, you can create an IAM user, grant the user required permissions, and obtain a token as the user.

{
    "error": {
        "code": 401,
        "message": "The username or password is wrong.",
        "title": "Unauthorized"
    }
}

Status Codes

Error Codes

None

Troubleshooting

• Incorrect username or password: Check whether the entered username and password are correct. If the username and password are correct but the error persists, check whether the account used to obtain a token is a HUAWEI ID. A HUAWEI ID cannot be directly used to obtain a token. You need to create an IAM user, assign required permissions to the user, and use the IAM username and password to obtain a token.
• No API access permissions: Before calling an API, ensure that you have enabled programmatic access.

Related Operations

• If login protection has been enabled and the verification method has been set to MFA authentication, obtain a token as an IAM user by following the instructions provided in Obtaining a User Token Through Password and Virtual MFA Authentication.
• To obtain a token with Security Administrator permissions, see How Do I Obtain a Token with Security Administrator Permissions?