1. Authentication¶
Each request to API endpoints requires a token that a user can obtain by performing password or multi-factor authentication with scoped authorization.
Send a POST request to https://<controller_hostname>/api/v1/auth/tokens, where <controller_hostname> is the hostname of the controller node.
To perform administrative actions, send a request to authorize in the project admin with the admin’s password. For example:
# curl -i -H 'Content-Type: application/json' -d '
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"domain": {
"id": "default"
},
"name": "admin",
"password": "****"
}
}
},
"scope": {
"project": {
"domain": {
"id": "default"
},
"name": "admin"
}
}
}
}
' https://<controller_hostname>/api/v1/auth/tokens
If multi-factor authentication is activated for the user, you will receive a “401 UNAUTHORIZED” error. The response header will contain an Openstack-Auth-Receipt string. Pass it in an MFA-specific authorization request. Also pass a one-time password (OTP) in passcode. In addition, the response body will list the endpoints. For example:
curl -i -H 'Content-Type: application/json' -H 'Openstack-Auth-Receipt: gAAAAA<...>' -d '
{
"auth": {
"identity": {
"methods": [
"totp"
],
"totp": {
"user": {
"domain": {
"id": "default"
},
"name": "admin",
"passcode": "****"
}
}
},
"scope": {
"project": {
"domain": {
"id": "default"
},
"name": "admin"
}
}
}
}
' https://<controller_hostname>/api/v1/auth/tokens
If authorization is successful, the response header will contain the token in the X-Subject-Token header. Pass it in the X-Auth-Token header in all requests. For example:
HTTP/1.1 201 CREATED
Date: Fri, 03 Dec 2021 14:04:42 GMT
Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips mod_wsgi/3.4 Python/2.7.5
Strict-Transport-Security: max-age=63072000; includeSubdomains;
X-FRAME-OPTIONS: deny
Content-Security-Policy: frame-ancestors 'none';
X-Subject-Token: gAAAAA<...>
Vary: X-Auth-Token
x-openstack-request-id: req-16f1db39-a489-47f7-85e0-e7bea1923a16
Content-Length: 1311
Content-Type: application/json
{
"token": {
"is_domain": false,
"methods": [
"password"
],
"roles": [
{
"id": "a9d46a97899e437d9c0c7811e35dbdfa",
"name": "admin"
}
],
"expires_at": "2021-12-04T15:22:28.000000Z",
"project": {
"domain": {
"id": "default",
"name": "Default"
},
"id": "f8873e7627de485ba67c4c9efaa120e4",
"name": "admin"
},
"catalog": [
{
"endpoints": [
{
"region_id": null,
"url": "http://127.0.0.1:6556/v1",
"region": null,
"interface": "admin",
"id": "4ec796be0deb416bb6bc9f69eeb4e714"
},
{
"region_id": null,
"url": "http://127.0.0.1:6556/v1",
"region": null,
"interface": "public",
"id": "5203bd500c2c4d0b977ad7b38162655a"
}
],
"type": "vzapi",
"id": "37cab82fb6f4404a97222939a53da652",
"name": "vzapi"
},
{
"endpoints": [
{
"region_id": null,
"url": "http://127.0.0.1:35357/v3",
"region": null,
"interface": "admin",
"id": "eaf3bfd14fa74b26ab9111a960558d3a"
},
{
"region_id": null,
"url": "http://127.0.0.1:35357/v3",
"region": null,
"interface": "public",
"id": "f2516dd5ab27462b9c8414ed33ef30d2"
}
],
"type": "identity",
"id": "4cf3fa4abd394900af41a256d9da7af1",
"name": "keystone"
}
],
"user": {
"password_expires_at": null,
"domain": {
"id": "default",
"name": "Default"
},
"id": "6fcd14baaa4b47f1a9de372037c2b68a",
"name": "admin"
},
"audit_ids": [
"8E16Fjo2QeSIlFQfERRAJA"
],
"issued_at": "2021-12-03T15:22:28.000000Z",
"is_admin_project": true
}
}
As the external endpoints are proxied for more security, all of the links will be local. It is not recommended but possible to open the ports listed in the table with firewalld to access the endpoints directly.
Proxied endpoint |
Direct endpoint |
|---|---|
|
|
|
|
|
|
|
|
To execute API calls as a regular user while being authorized as an admin, pass that user’s ID and project ID in the X-Effective-User-ID and X-Effective-Project-ID HTTP headers, respectively. Obtain the IDs from /api/v1/projects and /api/v1/users.
To authorize as a regular user within the scope of that user’s project, send the same requests as above, passing the user name, password, passcode, and the project name (same as the user name). Regular users do not need to pass the X-Effective-User-ID and X-Effective-Project-ID HTTP headers.