Enable Two-Factor Authentication for an Antares User¶

This guide describes how to enable TOTP-based two-factor authentication (2FA) for an Antares user.

The examples use the OpenStack CLI and the Antares cloud profile:

antares

The configured authentication rule is:

password + TOTP

This means the user must authenticate using both:

1. Their Antares password
2. A time-based one-time password (TOTP) generated by an authenticator application

Examples of compatible authenticator applications include:

• FreeOTP
• Google Authenticator
• Microsoft Authenticator
• 1Password
• Bitwarden

Prerequisites¶

Verify that the OpenStack CLI is installed:

openstack --version

Verify access to Antares:

openstack token issue \
    --os-cloud=antares

Administrative permissions are required to modify another user's 2FA configuration.

Official OpenStack documentation:

• OpenStackClient documentation
• OpenStackClient authentication
• Keystone Multi-Factor Authentication

1. Find the Antares User¶

List the available users:

openstack user list \
    --os-cloud=antares

Example:

+----------------------------------+---------------------+
| ID                               | Name                |
+----------------------------------+---------------------+
| 5d074c4566ef461697293877f78c0198 | example-user        |
+----------------------------------+---------------------+

If the username is already known, query the user directly:

openstack user show example-user \
    --os-cloud=antares

To return only the user ID:

openstack user show example-user \
    -f value \
    -c id \
    --os-cloud=antares

Example result:

5d074c4566ef461697293877f78c0198

Store the user ID for the following steps:

USER_ID=5d074c4566ef461697293877f78c0198

Official OpenStack documentation:

• OpenStack Identity user commands

2. Create a TOTP Secret¶

The Antares user requires a shared TOTP secret.

The secret must be Base32 encoded and should contain sufficient random entropy.

A secret can be generated with Python:

python3 -c 'import base64,secrets; print(base64.b32encode(secrets.token_bytes(20)).decode().rstrip("="))'

Example result:

JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP

Store the generated secret:

TOTP_SECRET="JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP"

Treat the TOTP secret like a password. Anyone with this secret can generate valid one-time passwords for the user.

Official OpenStack documentation:

• Keystone TOTP authentication

3. Create the TOTP Credential¶

Create a TOTP credential for the Antares user:

openstack credential create \
    --type totp \
    "$USER_ID" \
    "$TOTP_SECRET" \
    --os-cloud=antares

Using the example user ID directly:

openstack credential create \
    --type totp \
    5d074c4566ef461697293877f78c0198 \
    "$TOTP_SECRET" \
    --os-cloud=antares

The command creates a credential of type:

totp

Verify that the credential exists:

openstack credential list \
    --user "$USER_ID" \
    --type totp \
    --os-cloud=antares

Example:

+----------------------------------+----------------------------------+------+---------+
| ID                               | User ID                          | Type | Project |
+----------------------------------+----------------------------------+------+---------+
| aabbccddeeff00112233445566778899 | 5d074c4566ef461697293877f78c0198 | totp | None    |
+----------------------------------+----------------------------------+------+---------+

Official OpenStack documentation:

• OpenStack credential commands
• Keystone TOTP authentication

4. Add the TOTP Secret to an Authenticator¶

The user must now add the generated secret to an authenticator application.

Use the following values:

Account: <Antares username>
Secret:  <TOTP_SECRET>
Type:    TOTP

For example:

Account: example-user
Secret:  JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP

Most authenticator applications allow the secret to be entered manually.

The authenticator will then generate a six-digit one-time password that changes periodically.

Do not enable mandatory 2FA until the user has successfully added the TOTP secret to their authenticator.

Official OpenStack documentation:

• Keystone TOTP authentication

5. Enable Two-Factor Authentication¶

Enable multi-factor authentication for the Antares user:

openstack user set \
    --enable-multi-factor-auth \
    --multi-factor-auth-rule 'password,totp' \
    "$USER_ID" \
    --os-cloud=antares

Using the example user ID:

openstack user set \
    --enable-multi-factor-auth \
    --multi-factor-auth-rule 'password,totp' \
    5d074c4566ef461697293877f78c0198 \
    --os-cloud=antares

The configured rule requires both authentication methods:

password
totp

The Antares user must now provide both their password and a valid TOTP code when authenticating through an authentication flow that requires this MFA rule.

Official OpenStack documentation:

• OpenStack Identity user commands
• Keystone Multi-Factor Authentication

6. Verify the 2FA Configuration¶

Display the Antares user:

openstack user show "$USER_ID" \
    --os-cloud=antares

The user should show multi-factor authentication as enabled and contain a rule equivalent to:

password,totp

For example:

multi_factor_auth_enabled = True
multi_factor_auth_rules   = [['password', 'totp']]

The exact output formatting may depend on the installed OpenStackClient version.

Also verify that the user has a TOTP credential:

openstack credential list \
    --user "$USER_ID" \
    --type totp \
    --os-cloud=antares

Official OpenStack documentation:

• OpenStack Identity user commands
• OpenStack credential commands
• Keystone Multi-Factor Authentication

7. Authenticate with Password and TOTP¶

For CLI authentication using password and TOTP, the OpenStackClient supports the v3multifactor authentication plugin.

The authentication methods are:

v3password
v3totp

A suitable clouds.yaml entry can look like:

clouds:
  antares-mfa:
    auth:
      auth_url: https://<identity-endpoint>/v3
      username: example-user
      password: <PASSWORD>
      project_name: <PROJECT>
      user_domain_name: <DOMAIN>
      project_domain_name: <DOMAIN>
    auth_type: v3multifactor
    auth_methods:
      - v3password
      - v3totp

The current TOTP passcode can be supplied using:

export OS_PASSCODE=123456

Test the Antares authentication:

openstack token issue \
    --os-cloud=antares-mfa

TOTP codes are short-lived. Always use the currently displayed code from the user's authenticator application.

Avoid storing passwords or TOTP codes permanently in configuration files or shell scripts.

Official OpenStack documentation:

• OpenStackClient authentication
• Keystone Multi-Factor Authentication
• Keystone TOTP authentication

8. List a User's TOTP Credentials¶

To list the configured TOTP credentials for an Antares user:

openstack credential list \
    --user "$USER_ID" \
    --type totp \
    --os-cloud=antares

Example:

+----------------------------------+----------------------------------+------+---------+
| ID                               | User ID                          | Type | Project |
+----------------------------------+----------------------------------+------+---------+
| aabbccddeeff00112233445566778899 | 5d074c4566ef461697293877f78c0198 | totp | None    |
+----------------------------------+----------------------------------+------+---------+

The credential ID is required if the TOTP credential needs to be deleted later.

Official OpenStack documentation:

• OpenStack credential commands

9. Replace a Lost TOTP Device¶

If the user loses access to their authenticator, first identify the existing TOTP credential:

openstack credential list \
    --user "$USER_ID" \
    --type totp \
    --os-cloud=antares

Delete the old credential:

openstack credential delete \
    <CREDENTIAL_ID> \
    --os-cloud=antares

Generate a new TOTP secret:

TOTP_SECRET=$(python3 -c 'import base64,secrets; print(base64.b32encode(secrets.token_bytes(20)).decode().rstrip("="))')

Create a new credential:

openstack credential create \
    --type totp \
    "$USER_ID" \
    "$TOTP_SECRET" \
    --os-cloud=antares

The user must then add the new secret to their authenticator application.

The old TOTP secret should no longer be used after the credential has been replaced.

Official OpenStack documentation:

• OpenStack credential commands
• Keystone TOTP authentication

10. Disable Two-Factor Authentication¶

To disable multi-factor authentication for an Antares user:

openstack user set \
    --disable-multi-factor-auth \
    "$USER_ID" \
    --os-cloud=antares

Using the example user ID:

openstack user set \
    --disable-multi-factor-auth \
    5d074c4566ef461697293877f78c0198 \
    --os-cloud=antares

Disabling 2FA does not necessarily remove the stored TOTP credential.

If the credential should also be removed, list it:

openstack credential list \
    --user "$USER_ID" \
    --type totp \
    --os-cloud=antares

Delete the credential:

openstack credential delete \
    <CREDENTIAL_ID> \
    --os-cloud=antares

Verify the user configuration:

openstack user show "$USER_ID" \
    --os-cloud=antares

Official OpenStack documentation:

• OpenStack Identity user commands
• OpenStack credential commands

11. Login Problems and Support¶

If the user cannot log in to Antares after enabling two-factor authentication, first verify:

• The correct Antares username and password are being used.
• The TOTP code is the current code displayed by the authenticator application.
• The date and time on the device running the authenticator application are correct.
• The TOTP credential has been created for the correct Antares user.
• Multi-factor authentication is enabled for the correct Antares user.
• The configured MFA rule is password,totp.

An administrator can verify the Antares user's MFA configuration:

openstack user show "$USER_ID" \
    --os-cloud=antares

The user should have MFA enabled with a rule equivalent to:

password,totp

Verify that a TOTP credential exists:

openstack credential list \
    --user "$USER_ID" \
    --type totp \
    --os-cloud=antares

If the user has lost access to their authenticator application, the TOTP credential may need to be replaced as described in the previous section.

Antares Support¶

If the problem cannot be resolved, please use our help and support page:

https://support.net.de

When opening a support request, please provide:

• Your Antares username
• Your Antares project name, if applicable
• A short description of the problem
• The exact error message
• Whether the problem started before or after enabling 2FA

Never include your password, TOTP secret, current TOTP code, access credentials, or other secrets in a support request.

Official OpenStack documentation:

• Keystone Multi-Factor Authentication
• Keystone TOTP authentication
• OpenStackClient authentication

Quick Reference¶

1. Find the Antares User ID¶

USER_ID=$(openstack user show example-user \
    -f value \
    -c id \
    --os-cloud=antares)

Check the result:

echo "$USER_ID"

2. Generate a TOTP Secret¶

TOTP_SECRET=$(python3 -c 'import base64,secrets; print(base64.b32encode(secrets.token_bytes(20)).decode().rstrip("="))')

Display the secret:

echo "$TOTP_SECRET"

3. Create the TOTP Credential¶

openstack credential create \
    --type totp \
    "$USER_ID" \
    "$TOTP_SECRET" \
    --os-cloud=antares

4. Configure the Authenticator¶

Add the generated secret to the user's authenticator application:

Account: <Antares username>
Secret:  <TOTP_SECRET>
Type:    TOTP

5. Enable 2FA¶

openstack user set \
    --enable-multi-factor-auth \
    --multi-factor-auth-rule 'password,totp' \
    "$USER_ID" \
    --os-cloud=antares

6. Verify¶

openstack user show "$USER_ID" \
    --os-cloud=antares

List the TOTP credential:

openstack credential list \
    --user "$USER_ID" \
    --type totp \
    --os-cloud=antares

Recommended Procedure¶

The recommended order for enabling 2FA is:

Find the Antares user
        |
        v
Generate a TOTP secret
        |
        v
Create the TOTP credential
        |
        v
Configure the user's authenticator
        |
        v
Enable password + TOTP authentication
        |
        v
Verify the configuration
        |
        v
Test the Antares login

Do not enable mandatory password,totp authentication before the user has configured the TOTP secret. Otherwise, the user may be unable to authenticate to Antares.

Further Documentation¶

Official OpenStack documentation:

• Keystone Multi-Factor Authentication
• Keystone TOTP Authentication
• OpenStackClient Documentation
• OpenStackClient Authentication
• OpenStackClient Identity Commands
• OpenStackClient Credential Commands

Antares help and support:

• https://support.net.de