Obtaining a User Token Through Password and Virtual MFA Authentication

Function

This API is provided for IAM users to obtain a token through username/password and virtual MFA authentication. To use this API, ensure that virtual MFA-based login protection has been enabled for the IAM user. A token is an access credential issued to a 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 token for authentication.

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

Quick links

Obtaining a token as an IAM user

Checking whether the current account is a HUAWEI ID or a Huawei Cloud account

Obtaining a token using a HUAWEI ID

Obtaining a token using a Huawei Cloud account

Obtaining a token as a third-party system user

Validity period of a token

FAQs about obtaining a token

Related operations

• Obtaining a token as an IAM user

  See Request Parameters.

• Checking whether the current account is a HUAWEI ID or a Huawei Cloud account

  Check whether your account has been upgraded from Huawei Cloud account to HUAWEI ID by referring to How Do I Know What Account I Am Logged In With?

• Obtaining a token using a HUAWEI ID

  You cannot directly use a HUAWEI ID to obtain a token. You need to create an IAM user, assign permissions to the user, and use the user to obtain a token.

• Obtaining a token using a Huawei Cloud account

  See Request Parameters.

• Obtaining a token as a third-party system user

  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. Instead, you should go to the Huawei Cloud login page, click Forgot password, click Reset Huawei Cloud account password, and set a password.

• Validity period of a token
  • The validity period of a token is 24 hours. Cache the token to prevent frequent API calling. Ensure that the token is valid while 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 (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.
• FAQs about obtaining a token

  Incorrect user name or password: Check whether the entered user name and password are correct. If the username and password are correct but the error persists, check whether you have used a HUAWEI ID to obtain a token. A HUAWEI ID cannot be directly used to obtain a token. You need to create an IAM user, grant permissions to the user, and use the user to obtain a token.

  No API access permissions: Before calling an API, ensure that you have enabled programmatic access.

• Related operations
  • To obtain a token with Security Administrator permissions, see How Do I Obtain a Token with Security Administrator Permissions?
  • For details on how to obtain a token using Postman, see How Do I Obtain a User Token Using Postman?

Debugging

You can debug this API in API Explorer.

URI

POST /v3/auth/tokens

Request Parameters

Example Request

• Example 1: Request for obtaining a token for IAM user 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",
                  "totp"
              ],
              "password": {
                  "user": {
                      "name": "IAMUser",                            // IAM username.
                      "password": "IAMPassword",                   // IAM user password.
                      "domain": {
                          "name": "IAMDomain"                      // Name of the account used to create the IAM user.
                      }
                  }
              },
              "totp": {
                  "user": {
                      "id": "7116d09f88fa41908676fdd4b039e...",  // IAM user ID.
                      "passcode": "******"                           // Virtual MFA verification code.
                  }
              }
          },
          "scope": {
              "domain": {
                  "name": "IAMDomain"                                 // Name of the account used to create the IAM user.
              }
          }
      }
  }

• Example 2: Request for obtaining a token for IAM user 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",
                  "totp"
              ],
              "password": {
                  "user": {
                      "name": "IAMUser",                            // IAM username.
                      "password": "IAMPassword",                   // IAM user password.
                      "domain": {
                          "name": "IAMDomain"                      // Name of the account used to create the IAM user.
                      }
                  }
              },
              "totp": {
                  "user": {
                      "id": "7116d09f88fa41908676fdd4b039e...",  // IAM user ID.
                      "passcode": "******"                           // Virtual MFA verification code.
                  }
              }
          },
          "scope": {
              "project": {
                  "name": "ap-southeast-1"                                //Project name
              }
          }
      }
  }

Response Parameters

Example Response

Status code: 201

The request is successful.

• Example 1: Response to the request for obtaining a token for IAM user 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": {
          "expires_at": "2020-01-04T09:08:49.965000Z",
          "mfa_authn_at": "2020-01-03T09:08:49.965000Z",
          "methods": [
              "password",
              "totp"
          ],
          "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"
          },
          "roles": [
              {
                  "id": "0",
                  "name": "te_admin"
              },
              {
                  "id": "0",
                  "name": "secu_admin"
              },
              {
                  "id": "0",
                  "name": "te_agency"
              }
          ],
          "issued_at": "2020-01-03T09:08:49.965000Z",
          "user": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "7116d09f88fa41908676fdd4b039e...",
              "name": "IAMUser",
              "password_expires_at": ""
          }
      }
  }

• Example 2: Response to the request for obtaining a token for IAM user 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": {
          "expires_at": "2020-01-04T09:05:22.701000Z",
          "mfa_authn_at": "2020-01-03T09:05:22.701000Z",
          "methods": [
              "password",
              "totp"
          ],
          "catalog": [],
          "roles": [
              {
                  "id": "0",
                  "name": "te_admin"
              },
              {
                  "id": "0",
                  "name": "op_gated_OBS_file_protocol"
              },
              {
                  "id": "0",
                  "name": "op_gated_Video_Campus"
              }
          ],
          "project": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "aa2d97d7e62c4b7da3ffdfc11551f...",
              "name": "ap-southeast-1"
          },
          "issued_at": "2020-01-03T09:05:22.701000Z",
          "user": {
              "domain": {
                  "id": "d78cbac186b744899480f25bd022f...",
                  "name": "IAMDomain"
              },
              "id": "7116d09f88fa41908676fdd4b039e...",
              "name": "IAMUser",
              "password_expires_at": ""
          }
      }
  }

Status code: 400

Invalid parameters.

{
    "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, click Reset Huawei Cloud account password, and set a new 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