Multi-factor authentication#

Use the following multi-factor authentication API operations to configure and manage multi-factor authentication settings for Rackspace Cloud Accounts. For more information, see Using multi-factor authentication.

Note

  • Users can always use the MFA services on themselves.

  • Users with the identity:service-admin role can preform MFA operations for users with the identity:admin role, users with the identity:user-admin role, and sub-users.

  • Users with the identity:admin role can preform MFA operations for users with the identity:user-admin role and sub-users.

  • Users with the identity:user-admin or identity:user-manage role can preform MFA operations for users within their domain and with the identity:default role.

The functionality described in this section is provided by the

RAX-AUTH extension.

Add a mobile phone#

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones

Adds a mobile phone number to the specified user account to support multi-factor authentication.

The operation updates the specified user account with a phone number for multi-factor authentication. The same phone number can be associated with multiple accounts.

Add mobile phone: cURL request

$ curl $AUTH_URL/v2.0/users/$USER_ID/RAX-AUTH/multi-factor/mobile-phones  \
       -X POST \
       -H "Content-Type: application/json" \
       -H "X-Auth-Token: $AUTH_TOKEN"
       -d '{"RAX-AUTH:mobilePhone": { "number": "+1 210-312-4600" }}'| python -m json.tool`

Note

This example assumes that the endpoint URL, user ID, and authentication token have been exported to these environment variables: AUTH_URL, USER_ID, and AUTH_TOKEN.

This table shows the possible response codes for this operation:

Response Code

Name

Description

201

Success

The mobile phone has been added to the user account.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid. For example, you might get this error if the phone number format is incorrect.

401

Unauthorized

You are not authorized to complete this operation.

403

Forbidden

You do not have permission to access the requested resource. This error might be returned if the user ID is invalid or if it does not exist.

500

Service Fault

The service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

This table shows the body parameters for the request:

Name

Type

Description

RAX-AUTH:mobilePhone

Object

Provides the mobile phone information for the account.

RAX-AUTH:mobilePhone.number

String (Required)

The phone number for the mobile phone you want to add in E.123 format. +1 235-435-623 or +44 42 1123 4567 for example.

Example: Add a mobile phone HTTP request header: XML

POST /v2.0/users/10d2c2d0f3b644b9abea0d9fe8123456/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 6cac79a5c16343abb7c41b6bee123456
Content-type: application/xml

Example: Add a mobile phone request: XML

POST /v2.0/users/10d2c2d0f3b644b9abea0d9fe8123456/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 6cac79a5c16343abb7c41b6bee123456
Content-type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<RAX-AUTH:mobilePhone number="+1 210-312-4600"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Add a mobile phone HTTP request header: JSON

POST /v2.0/users/10d2c2d0f3b644b9abea0d9fe8123456/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 6cac79a5c16343abb7c41b6bee123456
Content-type: application/json

Example: Add mobile phone request: JSON

{
    "RAX-AUTH:mobilePhone": {
    "number": "+1 210-312-4600"
    }
 }

Response#

This table shows the body parameters for the response:

Name

Type

Description

id

String (Required)

The unique, system- generated ID assigned to the phone added to the account.

verified

Boolean (Optional)

A Boolean value that indicates whether the phone can be used to authenticate to the Identity service. Phones can be verified by using the Send verification code and Verify device operations.

number

String (Required)

The phone number added to the user account for use with multi-factor authentication services. E.123 format. +1 235-435-623 or +44 42 1123 4567 for example.

Example: Add a mobile phone response: XML

<?xml version="1.0" encoding="UTF-8"?>
<mobilePhone id="e0de732f1b1c4fec9d4f266326123456" verified="false" number="+1 210-312-4600"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Add a moble phone response: JSON

{
    "RAX-AUTH:mobilePhone": {
        "id": "e0de732f1b1c4fec9d4f266326123456",
        "number": "+1 210-312-4600"
    }
}

Send verification code to phone#

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones/{phoneId}/verificationcode

This operation sends an SMS message with a PIN code to a phone added to an account for multi-factor authentication.

After you update an account with a mobile phone number for multi-factor authentication, Rackspace must confirm that the user has the phone before it can be enabled for use in the authentication process.

When you send the verification code, include the phoneId in the API request. If you don’t know the ID, use the List multi-factor devices associated with operation to get it.

After you submit request, the Rackspace verification service sends a PIN to the specified phone via SMS text message. Each PIN has a system-defined expiration time determined by the Identity service system configuration. After receiving the PIN, use the Verify a mobile phone operation to submit the PIN to the Identity service to confirm the device for use with multi-factor authentication services.

Important

In the Send Verify request, the X-Auth-Token header parameter value must specify a valid authentication token ID for the user account associated with the mobile phone. If you submit an authentication token from any other account, the operation fails.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

The request was accepted for processing.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{userId}

String (Required)

The unique, system- generated user ID for an account.

X-Auth-Token

String (Required)

A valid authentication token.

{phoneId}

String (Required)

The ID for the phone associated with the user account.

This operation does not accept a request body.

Example Send verification code: JSON request in a cURL command

$ curl $AUTH_URL/v2.0/users/$USER_ID/RAX-AUTH/multi-factor/mobile-phones/$PHONE_ID/verificationcode \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Auth-Token: $AUTH_TOKEN"        | python -m json.tool

Note

This example assumes that the endpoint URL, user ID, and your authentication token have been exported to environment variables.

Response#

This operation does not return a response body.

Verify a mobile phone#

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones/{phoneId}/verify

Use this operation to submit the verification PIN from the SMS text message sent by Rackspace. After the PIN is accepted, use the Update settings for multi-factor authentication operation to enable multi-factor authentication on the user account.

When you send the verification code, include the phoneId in the API request. If you don’t know the ID, use the List phones for user operation to get it.

This operation can only be completed from the user account that the phone is associated with. The operation fails if the PIN is expired, or if it doesn’t match the code issued by the Rackspace verification service.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

415

Bad Media Type

Bad media type. This may result if the wrong media type is used in the API request. Check the content-type and accept headers included in the request.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

{phoneId}

String (Required)

The unique, system- generated ID assigned when a phone is added to an account.

This table shows the body parameters for the request:

Name

Type

Description

RAX-AUTH:verificationCode

Object

Provides the value to verify a phone for multifactor authentication.

RAX-AUTH:verificationCode.code

String (Required)

The unique PIN code from the SMS text message sent by the Rackspace Cloud verification service.

Example: Verify device: XML request

<?xml version="1.0" encoding="UTF-8"?>
<verificationCode
     code="1234"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Verify device: JSON request

{
    "RAX-AUTH:verificationCode": {
        "code": "1234"
    }
}

Response#

This operation does not return a response body.

List multi-factor mobile phone by device ID#

GET v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones/{mobilePhoneId}

When you configure a user account with multi-factor authentication by mobile phone, the Identity system assigns a unique device ID to the phone. If you know the device ID, you can use this operation to look up the phone number associated with the specified ID.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

{mobilePhoneId}

URI String (Required)

The unique, system- generated ID for a mobile phone that has been registered for use as a multi-factor authentication device.

This operation does not accept a request body.

Example: Retrieve multi-factor phone for a user HTTP request header: XML

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c12345/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234
Content-type: application/json

Example: Retrieve multi-factor phone for user by device ID request header: JSON

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c12345/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234
Content-type: application/json

Response#

This table shows the body parameters for the response:

Name

Type

Description

RAX-AUTH:mobilePhones

Object (Required)

An array that returns phone ID and status information.

RAX-AUTH:mobilePhones.id

String (Required)

A unique, system- generated string that identifies the mobile phone in the Identity service.

RAX-AUTH:mobilePhones.number

String (Required)

Phone number of the device associated with the user account. Use the Add mobile phone operation to add a phone to the account. Use the remove multi-factor operation to delete phones from the account.

RAX-AUTH:mobilePhones.verified

Boolean (Optional)

A Boolean value that indicates whether the phone can be used to authenticate to the Identity service. Phones can be verified by using the Send verification code and Verify device operations.

Example: Lists multi-factor phones for user response: XML

<?xml version="1.0" encoding="UTF-8"?>
<mobilePhone id="12345" number="12658943489" verified="false"
  xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
  xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
  xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Lists multi-factor phones for user response: JSON

{
 "RAX-AUTH:mobilePhone": {
   "id": "12345",
   "verified": false,
   "number": "12658943489"
  }
}

List multi-factor phones for user#

GET /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones

Use this operation to get a list of the mobile phones associated with the specified user account.

A user or Identity administrator impersonating a user can use this operation to list the mobile phones associated with a user account.

You can retrieve a specific phone by including the unique, system-generated ID assigned to the phone when it was added to the Rackspace Cloud account.

An account can have up to one mobile phone configured for multi-factor authentication.

If you don’t know the user ID, use the List user operation to find it.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example List multi-factor phones for user: XML request

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c12345/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234
Content-type: application/json

Example List multi-factor phones for user request: JSON request

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c12345/RAX-AUTH/multi-factor/mobile-phones HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234
Content-type: application/json

Response#

This table shows the body parameters for the response:

Name

Type

Description

RAX-AUTH:mobilePhones

Object (Required)

An array that returns phone ID and status information.

id

String (Required)

A unique, system- generated string that identifies the mobile phone in the Identity service.

number

String (Required)

Phone number of the device associated with the user account. Use the Add mobile phone operation to add a phone to the account. Use the remove multi-factor operation to delete phones from the account.

verified

Boolean (Optional)

A Boolean value that indicates whether the phone can be used to authenticate to the Identity service. Phones can be verified by using the Send verification code and Verify device operations.

Example Lists multi-factor phones for user: XML response

<?xml version="1.0" encoding="UTF-8"?>
<mobilePhones
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0">
     <mobilePhone id="12345" number="+1 265-894-3489" verified="true"/>
</mobilePhones>

Example Lists multi-factor phones for user: JSON response

{
  "RAX-AUTH:mobilePhones": [
    {
      "id": "12345",
      "verified": true,
      "number": "12658943489"
    }
  ]
}

Remove phone from account#

DELETE /v2.0/users/{userId}/RAX-AUTH/multi-factor/mobile-phones

Removes a phone number associated with a user account to support multi-factor authentication.

This operation removes the multi-factor authentication setting from your account along with all phones associated with the account. To disable the feature without removing phones, use the Disable multi-factor setting operation.

This operation allows users and administrators to remove a mobile phone number added to an account to support multi-factor authentication. You can remove the number if multi-factor authentication is disabled, or if the user has decided to use an OTP device for multi-factor authentication.

This operation can only be completed from the user account submitting the request. Attempts to run it for a different user ID result in a 403 error message.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example: Remove phone from account: XML request

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/1234 HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234
Content-type: application/xml

Example: Remove phone from account: JSON request

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/1234 HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234
Content-type: application/json

Response#

This operation does not return a response body.

Create an OTP device#

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices

Adds an OTP (one-time password) device for multi-factor authentication.

You can add up to five OTP devices to a user account. After adding the device, use the verify OTP device.

This table shows the possible response codes for this operation:

Response Code

Name

Description

201

Success

The OTP device has been added to the user account.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation.

500

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example: Add an OTP device HTTP request header: XML

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1
Host: staging.identity-internal.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 83aa159390854e4690e4834e0cfa1234
Content-type: application/xml

Example: Add an OTP device request: XML

<?xml version="1.0" encoding="UTF-8"?>
<otpDevice name="NewOTPDevice"
     xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Add an OTP device HTTP request header: JSON

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1
Host: staging.identity-internal.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 83aa159390854e4690e4834e0cfa1234
Content-type: application/json

Example: Add an OTP device request: JSON

{
    "RAX-AUTH:otpDevice": {

        "name": "NewOTPDevice"

    }
}

Response#

This table shows the header parameters for the response:

Name

Type

Description

Location

AnyURI (Required)

URI for the newly created OTP device.

This table shows the body parameters for the response:

Name

Type

Description

id

String

The unique, system- generated ID assigned to the OTP device.

keyUri

String

The URI for the device security token.

name

String

The unique name assigned to the OTP device.

qrcode

String

The bar code to identity the OTP device to the mobile passcode application.

verified

Boolean

Indicates whether the OTP device has been verified.

Example: Add an OTP device HTTP response header: XML

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c
Content-type: application/json

Example: Add an OTP device response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rax-auth:otpDevice
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns="http://docs.openstack.org/identity/api/v2.0"
     xmlns:ns4="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
     xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
     xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
     xmlns:os-ksec2="http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">
     <rax-auth:otpDevice
          id="6b2834a8bef6461e96ef2322b4c72998"
          keyUri="otpauth://totp/Example:alice@google.com?secret\u003dJBSWY3DPEHPK3PXP\u0026issuer\u003dExample"
          qrcode="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAoAAAAKAAQAAAAAktvSOAAADJklEQVR42u3dPXLqMBAAYGVekTJHyFFytHA0juIjpKRg0HP8I68E5Gcmtik+NyAwH51md7WSU/7jKwGBQCAQCAQCgUAgEAgEAoFAIBC4Bpji9T5+dkovw+shpacyPPbf9y/neP8TEAgE7gcuHx57MNz91oPTNx/TsL/5nJ5v/RYIBAJ3AMcp7nUEx+E8AU7XS7z5efDTeDMQCAQ+CDgEbJ8zXjdHd6PfDfdM3wKBQODjgf2bf0P62fXxW5kA85ScAoFA4EOBV9no/JNSPbvpZyAQCNwVrNcCSr4ZktNm+LvFBSAQCFwJbDsqYvXskK6nx9+2dgCBQOBKYEk/p16LyzAMtbXxCuHcnLpWPhAIBG4NhvrY0HrxCeYpfktxPnyb/z1/nY0CgUDgRuCl3HMcE8xY7S9tsd2Sq1apKxAIBO4FVo2veV4LyEvrxdwHW5Xa0hzdAYFA4G5g0/i6DEMxbcxGmyEQCATuCvbhXCz+D8Pnko3m3LaZpWmYgUAgcF9wWgsoe8AvZWkg5Kofy57K8+2VTSAQCNwcfLpuqziVPeBtJ0b8uwMQCAQ+CDh1YqTQ+Bo6Maq1gNdczucBAoHAfcAiNJ0Y5ZobM6ba2rLu+X6nsRYIBAI3AUvAVm07KtX+q+L/OZTa7q+NAoFA4Opg6bUI5f3TErClUExrams532vjBwKBwK3AUwnepuiuHCB2qQ7k+UkxDQgEAjcCl+pZk2/eng/j331dTAMCgcBVwWqx8r09X7q0mXVxU9J3jWRAIBC4ARimuLec6+Nbw2Jl1x4vlu9mo0AgELgJeGsXUrPP6FRvsVw6MYBAIHBHsJ3XUr0L6VKEsHYZ1j2BQCBwL/D69Okci/+5it+qcO6Q7jeSAYFA4Ppg/eyPcnxrKKZdnVkRHoMLBAKBO4LNgyNv9pVNs2V9hMVX6S0QCARuC4YTLUI4l2N0992zkIBAIHAPsBxGHfpgl02UIdj7cTgHBAKBq4ExGw27kI5VnW0RTt+Gc0AgELgFeLUWcC6Nr+HEsC6uFKTfLS4AgUDgGuAfXUAgEAgEAoFAIBAIBAKBQCAQCAQ+MvgfowFRJtozjAcAAAAASUVORK5CYII\u003d",
          name="NewOTPDevice">
</rax-auth:otpDevice>

Example: Add a moble phone HTTP response header: JSON

HTTP/1.1 200 OK
Content-Length: 1985
Content-Type: application/json
LOCATION: http://identity.api.rackspacecloud.com/cloud/v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/a34b5e4a1ffe4514a8859716136dc7cb
Date: Tue, 05 May 2015 14:09:02 GMT

Example: Add a moble phone response: JSON

{
    "RAX-AUTH:otpDevice": {
        "id": "58c4e0f6ca9745a9b97bcad9796685cd",
        "keyUri": "otpauth://totp/Rackspace:AngelaTestMobile1?secret=IU4K3ZYVOKKCI4Z3UZTSKBXOCWMXVGLW&issuer=Rackspace",
        "name": "NewOTPDevice",
        "qrcode": "data:image/png;base64,tVBORw0KGgoAAAANSUhEUgAAAoAAAAKAAQAAAAAktvSOAAADQUlEQVR42u3dS3KrMBCF4WbEMlgqLJVlMELXwRI6rQeRkztK/UxSEPw5I5X6oY6F/3wZICAgICAgICAgICAgICAgICDgHwcPy9f0ulvej3dbz9eT191p89fd++F1LWGTDy2AgICAY2B6ErYInteLa8h3+VvuN6uPAwICAn4LbnFRmq7FLErpLi5fZ1q35vTVfr0DBAQE/BS0Ke2g5rQ9it8SHwICAgL+GrzCrynHazE0CykY80sbICAg4GeghmbXazEKKxesRX4Mx3qAgICAnbTzNvDjozw2ICAgYPNqJHtMEkGZGK3RAwICAsblK+2LJlfruotcc65upevMSaIFEBAQcASU1M/6zvloA08OzUxrXekPkQ8AAgICPoNHEZPlRND9drlZ0lguAAICAo6BdZ+g+Ttz+6IzhW2+axAQEBDwe1D3RZa3QDEflAlpHsw7qHZoBggICNisSfnUjy5mvke56uOxZqwHCAgI2EkE6e/3dj1rK/NB8zuBFAABAQHHQC2bxyS05fDr/uxaltsDICAg4EdgrJD7LPLN6wqnVTFLy9fRbhcEBAQEbB6F0NJ4uW65tFB1/qq1HgICAgI+gbucuGrukqTktdYrHCAgIOAgGMqSuiSJzM3l2osgDhAQEHAI9NNw9IDD4Vp25Fv8gVBAQEDAATDICK6zcb6zMazrPgphvZI6ICAgYLuBR4YB5lr6WT201Fi4nvXZckBAQMARUNM7MtP4zg6Zn13hjoACAgICDoDlvkibk+ecK9KHz0chAAEBAbfe/5NqvJ2TPdYiHpcvQEBAwM5mKfiuZJcWCqEasl4N6wIEBAQcBKWkvhRdg7llx6eMQlH5AgQEBHwGtYLVeE2yz6FYzJ4SQYCAgIDdzVLotOz4oxAy7KLTnAwICAjYOblQThLV6nk1PsfMiiGlgICAgIOgBmNHMV60cX68McgLEBAQcAz07YL+Q6Gc+ydJaEBAQMCfgnXzoMmEQG31eZj3BQgICDgA7i1CQ7O5PE0OCAgIOAr60MxP4jJzU7p0wWqPVQcEBATcHkrq5o5CBNfOc7iWHflvndY9WwEICAi4PJbUf3EBAgICAgICAgICAgICAgICAgL+VfAf+kH5tccf0ykAAAAASUVORK5CYII=",
        "verified": false
    }
}

Verify an OTP device#

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices/{otpDeviceId}/verify

Sends the mobile passcode from the mobile passcode application to the Identity service to pair the OTP device instance with the account.

After you set up an OTP device for multi-factor authentication this operation sends the passcode from the mobile passcode application to the Identity service to confirm that you have the device so that you can use the device for multi-factor authentication.

If your account is set up for multi-factor authentication by using a mobile phone, or if this is the first OTP device on your account, update the multi-factor authentication settings on your account to use the OTP device.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

String (Required)

The unique, system- generated user ID for an account.

{otpDeviceId}

String (Required)

The unique system- generated ID assigned to the OTP device.

This table shows the body parameters for the request:

Name

Type

Description

verified

Boolean (Required)

Indicates whether the OTP device has been verified.

Example: : Verify OTP devices for account HTTP request header: XML

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/\
12345e4a1ffe4514a8859716136dc7cb/verify HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 83aa159390854e4690e4834e0c123456
Content-type: application/json

Example: : Verify OTP devices for account request: XML

<?xml version="1.0" encoding="UTF-8"?>
<verificationCode code="123456"
    xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
    xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: :Verify OTP devices for account HTTP request header: JSON

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/\
a34b5e4a1ffe4514a8859716136dc7cb/verify HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c
Content-type: application/json

Example: :Verify OTP devices for account request: JSON

{“RAX-AUTH:verificationCode”: { “code”: “662262” }}

Response#

Example: : Verify device by ID HTTP response

HTTP/1.1 204 No Content

List the specified OTP device#

GET /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices/{otpDeviceId}

This operation returns the OTP device associated with the account.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

The request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

{otpDeviceId}

String (Required)

The unique system- generated ID assigned to the OTP device.

This table shows the body parameters for the request:

Name

Type

Description

otpDevice

Object

Returns the following information for an OTP device: ID, name, verification status.

otpDevice.id

String

The unique system- generated ID assigned to the OTP device.

otpDevice.name

String

The unique name assigned to the OTP device.

otpDevice.verified

Boolean

Indicates whether the OTP device has been verified.

Example:: Get OTP devices for account HTTP request header: XML

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/6b2834a8bef6461e96ef2322b4c72998 HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c
Content-type: application/xml

Example:: Get OTP devices for account HTTP request header: JSON

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/6b2834a8bef6461e96ef2322b4c72998 HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c
Content-type: application/json

Response#

Example: Get OTP devices for account HTTP response header: XML

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

Example: Retrieves the specified OTP device response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rax-auth:otpDevices
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns="http://docs.openstack.org/identity/api/v2.0"
     xmlns:ns4="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
     xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
     xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
     xmlns:os-ksec2="http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">
     <rax-auth:otpDevice verified="true" name="NewOTPDevice" id="6b2834a8bef6461e96ef2322b4c72998"/>
</rax-auth:otpDevices>

Example: Get OTP devices for account HTTP response header: JSON

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

Example: Retrieves the specified OTP device response: JSON

{
    "RAX-AUTH:otpDevice": {
        "id": "6b2834a8bef6461e96ef2322b4c72998",
        "verified": true,
        "name": "NewOTPDevice"
    }
}

Get the OTP devices for a specified account#

GET /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices

This operation returns information about the OTP devices associated with a user account.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

The request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example: Get OTP devices for account HTTP request header: XML

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 9c069077e4eb438daf8527ba7cc0a7ad
Content-type: application/xml

Example: Get OTP devices for account HTTP request header: JSON

GET /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 9c069077e4eb438daf8527ba7cc0a7ad
Content-type: application/json

Response#

This table shows the body parameters for the response:

Name

Type

Description

otpDevices

Object

Returns the collection of OTP devices associated with the specified account.

otpDevices.otpDevice

Object

Returns information about each OTP device associated with the specified account.

otpDevice.id

String

The unique system- generated ID assigned to the OTP device.

otpDevice.name

String

The unique name assigned to the OTP device.

otpDevice.verified

Boolean

Indicates whether the OTP device has been verified.

Example: Gets the OTP devices for a specified account HTTP response header: XML

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

Example: Gets the OTP devices for a specified account response: XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rax-auth:otpDevices
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns="http://docs.openstack.org/identity/api/v2.0"
     xmlns:ns4="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
     xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
     xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
     xmlns:os-ksec2="http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">
     <rax-auth:otpDevice verified="false" name="NewOTPDevice1" id="22eec7c1f65a4615945d89e38786a6b3"/>
     <rax-auth:otpDevice verified="false" name="NewOTPDevice" id="a34b5e4a1ffe4514a8859716136dc7cb"/>
     <rax-auth:otpDevice verified="true" name="NewOTPDevice" id="6b2834a8bef6461e96ef2322b4c72998"/>
</rax-auth:otpDevices>

Example: Gets the OTP devices for a specified account HTTP response: JSON

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

Example: Gets the OTP devices for a specified account: JSON

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rax-auth:otpDevices
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:rax-auth="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns="http://docs.openstack.org/identity/api/v2.0"
     xmlns:ns4="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
     xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
     xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
     xmlns:os-ksec2="http://docs.openstack.org/identity/api/ext/OS-KSEC2/v1.0">
     <rax-auth:otpDevice verified="false" name="NewOTPDevice1" id="22eec7c1f65a4615945d89e38786a6b3"/>
     <rax-auth:otpDevice verified="false" name="NewOTPDevice" id="a34b5e4a1ffe4514a8859716136dc7cb"/>
     <rax-auth:otpDevice verified="true" name="NewOTPDevice" id="6b2834a8bef6461e96ef2322b4c72998"/>
</rax-auth:otpDevices>

Example: Get the OTP devices for a specified account HTTP response header: JSON

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

Example: Get the OTP devices for a specified account response: JSON

{
    "RAX-AUTH:otpDevices": [
        {
            "id": "22eec7c1f65a4615945d89e38786a6b3",
            "verified": false,
            "name": "NewOTPDevice1"
        },
        {
            "id": "a34b5e4a1ffe4514a8859716136dc7cb",
            "verified": false,
            "name": "NewOTPDevice2"
        },
        {
            "id": "6b2834a8bef6461e96ef2322b4c72998",
            "verified": true,
            "name": "NewOTPDevice"
        }
    ]
}

Remove a specified OTP device from a user account#

DELETE /v2.0/users/{userId}/RAX-AUTH/multi-factor/otp-devices/{otpDeviceId}

This operation deletes the OTP device with the specified ID from the user account.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

{otpDeviceId}

String (Required)

The unique system- generated ID assigned to the OTP device.

This operation does not accept a request body.

Example: Delete OTP device by ID: XML request header

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/6b2834a8bef6461e96ef2322b4c72998 HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c
Content-type: application/xml

Example: Delete OTP device by ID: JSON request

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/otp-devices/6b2834a8bef6461e96ef2322b4c72998 HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 83aa159390854e4690e4834e0cfa5f6c
Content-type: application/json

Response#

Example: Delete device by ID HTTP response

HTTP/1.1 204 No Content

This operation does not require a request body and does not return a response body.

Update multi-factor authentication settings on account#

PUT /v2.0/users/{userId}/RAX-AUTH/multi-factor

Use this operation to update the multi-factor authentication settings for the specified account.

You can only use this operation on accounts that have been set up for multi-factor authentication.

You can use the userMultiFactorEnforcementLevel parameter to override the multi-factor domain enforcement setting on an account. Note that this feature is available only through the API. You cannot override domain enforcement settings from the Rackspace Cloud Control Panel.

Note

  • Customers need a support ticket if they want to update a user’s MFA enforcement setting when the domain MFA enforcement setting is RACKSPACE_MANDATED.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

Possible reasons: No multi-factor device on user account; multi factor phone on account is not verified.

403

Forbidden

Possible reasons: No multi-factor device on user account; multi factor phone on account is not verified.

403

Forbidden

Cannot update user enforcement level when domain enforcement level set as RACKSPACE_MANDATED.

500

Service Fault

Problem linking phone with Identity service multi-factor authentication service. Contact the Identity service administrator for help.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

This table shows the body parameters for the request:

Name

Type

Description

RAX- AUTH:multiFactor

Object (Optional)

A collection of multi-factor authentication settings.

RAX-AUTH:multiFactor.enabled

Boolean (Optional)

If an account has been configured for multi-factor authentication, this parameter specifies whether the feature is active on the account. account.

Specify enabled=true to turn on multi-factor authentication.

Specify enabled=false to turn it on.

As soon as you enable multi-factor authentication on an account, any existing authentication tokens are are invalidated, and the account user must use multi-factor authentication process to regain access to their account.

RAX-AUTH:multiFactor.unlock

Boolean (Optional)

A Boolean value that indicates the lock status on a user account that is enabled for multi-factor authentication. To unlock an account, specify unlock=true in the Unlock operation request. .This attribute cannot be used to lock an account. If you submit the request with unlock=false, the operation does not make any changes to the account.

RAX-AUTH:multiFactor.userMultiFactorEnforcementLevel

String (Optional)

Specifies the user enforcement level for multi-factor authentication.

REQUIRED The user must use multi- factor authentication to log in to their Rackspace Cloud account even if the domain enforcement level is configured as optional.

OPTIONAL. The user has the option has the option to authenticate using multi-factor authentication even if the the domain enforcement level is configured as required.

DEFAULT. The user multi-factor authentication requirements are determined by the domain-level authentication.

Example: Enable account for multi-factor authentication HTTP request header: XML

PUT /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: ab502872c7cc415483c945bcfc77322c
Content-type: application/xml

Example: Enable account for multi-factor authentication: XML request

<?xml version="1.0" encoding="UTF-8"?>
<multiFactor
     enabled="true"
     xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Enable account for multi-factor authentication HTTP request header: JSON

PUT /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: ab502872c7cc415483c945bcfc77322c
Content-type: application/xml

Example: Enable multi-factor authentication on account request: JSON

{
    "RAX-AUTH:multiFactor": {
        "enabled": true
    }
}

Example: Disable multi-factor authentication on account HTTP request header: XML

PUT /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: ab502872c7cc415483c945bcfc77322c
Content-type: application/xml

Example: Disable multi-factor authentication on account request: XML

<?xml version="1.0" encoding="UTF-8"?>
<multiFactor
     enabled="false"
     xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Disable multi-factor authentication on account HTTP request header: JSON

PUT /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: ab502872c7cc415483c945bcfc77322c
Content-type: application/xml

Example: Disable multi-factor authentication on account request: JSON

{
    "RAX-AUTH:multiFactor": {
        "enabled": false
    }
}

Example: Unlock account request: XML

<?xml version="1.0" encoding="UTF-8"?>
<multiFactor
     unlock="true"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom"
     xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Unlock account request: JSON

{
    "RAX-AUTH:multiFactor": {
        "unlock": true
    }
}

This operation does not accept a response body.

Example: Update user level enforcement for multi-factor authentication request: XML

<multiFactor
    userMultiFactorEnforcementLevel="OPTIONAL"
    xmlns:RAX-AUTH="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
    xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>
</multiFactor>

Example: Update user level enforcement request: JSON

{
    "RAX-AUTH:multiFactor": {
        "userMultiFactorEnforcementLevel": "OPTIONAL",
    }
}

Response#

This operation does not return a response body.

Generate bypass codes#

POST /v2.0/users/{userId}/RAX-AUTH/multi-factor/bypass-codes

Use this operation to generate bypass codes that can be substituted for a multi-factor authentication passcode. You can use these codes to recover access to an account if you are unable to retrieve the multi-factor authentication passcode from your multi-factor authentication device. In the request, you can specify the number of bypass codes to generate and set an expiration date for the generated codes.

Administrator-generated codes are valid for 30 minutes by default. Administrators can configure the validity duration from 1 to 180 minutes.

Each bypass code can be used only one time. A bypass code remains valid until it expires. Bypass codes are also invalidated if multi-factor authentication is disabled on the account associated with the bypass code.

Note

  • You can also generate bypass codes from the Account settings page in the Rackspace Cloud Control panel.

  • Users can always use this service to generate bypass codes for themselves.

  • Users with the identity:user-admin role can generate a single bypass code for any user within their domain.

  • Users with the identity:user-manage or identity:user-manage-limited role can generate a single bypass code for any sub user within their domain.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

The request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

415

Bad Media Type

Bad media type. This may result if the wrong media type is used in the API request. Check the content-type and accept headers included in the request.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

This table shows the body parameters for the request:

Name

Type

Description

RAX-AUTH:bypassCodes

Object String (Optional)

This object specifies the validityDuration and numberofcodes attributes for the Generate bypass codes operation. See the XML and JSON request examples for the correct syntax.

RAX-AUTH:bypassCodes.validityDuration

Duration (Optional)

Specifies the time interval that the bypass codes remain valid.

  • If no value is specified, the value defaults to 30 minutes PT30M.

  • If the bypass codes are for your own account, customize the value as needed.

  • Administrators can configure an interval between 1 and 180 minutes when creating a bypass code for another user account.

The value is expressed in xsd:duration format, PT20MPnYnMnDTnHnMnS.

P indicates the period (required)

nY indicates the number of years

nM indicates the number of months

nD indicates the number of days

T indicates the start time of a section. (required if the duration value includes hours, minutes, or seconds)

nH indicates the number of hours

nM indicates the number of minutes

nS indicates the number of seconds

RAX-AUTH:bypassCodes.numberofcodes

Integer (Optional)

Specifies the number of bypass codes to generate codes to generate. If

If not specified, the value defaults to 1.

Users can generate up to 10 bypass codes for their own account.

Administrators can generate only one bypass code for user accounts other than their own.

Example: Generate bypass codes HTTP header request: XML

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/bypass-codes HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234
Content-type: application/xml

Example:Generate bypass codes request: XML

<?xml version="1.0" encoding="UTF-8"?>
<bypassCodes validityDuration="PT20M" numberOfCodes="1"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Generate bypass codes HTTP header request: JSON

POST /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor/bypass-codes HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: 9b830c07c29f4d17a7e53d2341301234
Content-type: application/json

Example:Generate bypass codes request: JSON

{
  "RAX-AUTH:bypassCodes": {
    "validityDuration": "PT20M",
    "numberOfCodes": "1"
  }
}

Response#

This table shows the body parameters for the response:

Name

Type

Description

RAX-AUTH:bypassCodes

Object String (Optional)

This object returns the list of bypass codes and the validityDuration setting that specifies how long the codes are valid. See the XML and JSON request examples for the correct syntax.

RAX-AUTH:bypassCodes.codes

String list (Optional)

Returns a list of the generated bypass codes.

RAX-AUTH:bypassCodes.validityDuration

Duration (Optional)

The time interval that specifies how long the generated codes remain valid.

Example: Generate bypass codes HTTP response header: XML

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

Example:Generate bypass codes response: XML

<?xml version="1.0" encoding="UTF-8"?>
<bypassCodes validityDuration="PT10M0.000S" codes="123456789"
     xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
     xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
     xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: Generate bypass codes HTTP response header: JSON

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

Example: Generate bypass codes response: JSON

{
  "RAX-AUTH:bypassCodes": {
    "codes": [
      "123456789"
    ],
    "validityDuration":"PT20M0.000S"
  }
}

Update domain enforcement setting#

PUT /v2.0/RAX-AUTH/domains/{domainId}/multi-factor

Updates the domain-level enforcement level for multi-factor authentication.

Identity administrators can set account-wide requirements for multi-factor authentication by setting the domain enforcement level. This setting applies to all user accounts within the domain specified in the update request. Before you set the domain enforcement level, the administrator account must be configured with multi-factor authentication.

Note

  • Administrators can override the domain-level enforcement level for specific user accounts by using the Update multi-factor authentication settings operation to set user level enforcement.

  • Customers need a support ticket if they want to update a domain to have the RACKSPACE_MANDATED mfa enforcement policy and also to update a domain’s mfa enforcement when it is already set to RACKSPACE_MANDATED.

Update domain enforcement settings:json cURL request

$ curl -X -i PUT identity.api.rackspacecloud.com/v2.0/RAX-AUTH/domains/$DOMAIN_ID/multi-factor \
  -d '{"RAX-AUTH:multiFactorDomain": {"domainMultiFactorEnforcementLevel": "OPTIONAL"}}` \
  -H "Content-type: application/json" \
  -H "X-Auth-Token: $ADMIN_AUTH_TOKEN" --verbose | python -m json tool

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400

Bad Request

Trying to set up domain- level enforcement setting on an account that has not been configured with multi- factor authentication. Set up multi-factor authentication on account.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

403

Forbidden

You must set up multi- factor authentication on your account before you can set multi-factor domain-level enforcement.

404

Not Found

The requested resource was not found.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the body parameters for the request:

Name

Type

Description

RAX- AUTH:multiFactorDomain

Object (Optional)

Specifies the domain enforcement level, domainMultiFactorEnforcementLevel for multi-factor authentication. Specify either of these values. * domainMultiFactorEnforcementLevel: "REQUIRED" makes multi-factor authentication mandatory for all account users. * domainMultiFactorEnforcementLevel: "OPTIONAL" Users within the domain can choose whether to use multi-factor authentication on their own accounts. domainMultiFactorEnforcementLevel: "RACKSPACE_MANDATED" makes multi-factor authentication mandatory for all account users. *

RAX-AUTH:multiFactorDomain.domainMultiFactorEnforcementLevel

String

The domain enforcement level for multi-factor authentication. Specify one of the following values:

  • REQUIRED

    Authentication is mandatory for all account users within the specified domain.

  • OPTIONAL

    Users within the specified domain can choose whether to use multi-factor authentication on their account.

  • RACKSPACE_MANDATED

    Authentication is mandatory for all account users within the specified domain.

Example: : Update domain settings for multi-factor authentication request: XML

<?xml version="1.0" encoding="UTF-8"?>
<multiFactorDomain domainMultiFactorEnforcementLevel="REQUIRED"
  xmlns="http://docs.rackspace.com/identity/api/ext/RAX-AUTH/v1.0"
  xmlns:OS-KSADM="http://docs.openstack.org/identity/api/ext/OS-KSADM/v1.0"
  xmlns:atom="http://www.w3.org/2005/Atom" xmlns:identity="http://docs.openstack.org/identity/api/v2.0"/>

Example: : Update domain settings for multi-factor authentication request: JSON

{

    "RAX-AUTH:multiFactorDomain": {
        "domainMultiFactorEnforcementLevel": "REQUIRED"
        }
}

Response#

This operation does not return a response body.

Remove mutlifactor authentication from account#

DELETE /v2.0/users/{userId}/RAX-AUTH/multi-factor

Removes the multi-factor authentication setting and all associated mobile phones from your user account.

This operation removes the multi-factor authentication setting from your account along with all phones associated with the account. To disable the feature without removing phones, use the update multi-factor settings on account operation to disable multi-factor authentication on the account.

Note

  • Users can always use this service to remove multi-factor authentication from themselves.

  • Users with the identity:user-admin role can remove multi-factor authentication from any user within their domain.

  • Users with the identity:user-manage or identity:user-manage-limited role can remove multi-factor authentication from any sub user within their domain.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No content

The request succeeded. The server fulfilled the request but does not need to return a body.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

The request was valid, but the server is refusing to respond because you do not have permission to access the requested resource. Submit a request to your account administrator to determine how to gain access.

405

Invalid Method

The method specified in the request is not valid for the resource identified in the request URI.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Fault

Service is not available.

Request#

This table shows the header and URI parameters for the request:

Name

Type

Description

X-Auth-Token

Header String (Required)

A valid admin authentication token.

{userId}

URI String (Required)

The unique, system- generated user ID for an account.

This operation does not accept a request body.

Example: Remove multi-factor authentication HTTP request header: XML

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/xml
X-Auth-Token: ab502872c7cc415483c945bcfc77322c
Content-type: application/xml

Example Remove multi-factor authentication HTTP request header JSON

DELETE /v2.0/users/e0fb2b4ddb594819b697d0048614c117/RAX-AUTH/multi-factor HTTP/1.1
Host: identity.api.rackspacecloud.com
Accept: application/json
X-Auth-Token: ab502872c7cc415483c945bcfc77322c
Content-type: application/json

Response#

This operation does not return a response body.