Authentication

This section describes:

  • How to change your Gaia login password.

  • How to enable and configure Two-Factor Authentication for Gaia login.

Changing Your Gaia Login Password

A Gaia user can change their Gaia login password - in Gaia Portal or Gaia Clish.

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

1

In the navigation tree, click User Management > Authentication.

Refer to the section Change Password.

2

In the Old Password field, enter your old password.

3

In the New Password field, enter the new password.

4

In the Confirm New Password field, enter the new password again.

5

Click Apply.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must run the applicable commands in Gaia gClish of the applicable Security Group.

Description

Change your Gaia login password in an interactive dialog.

Syntax

set selfpasswd

Warning - We do not recommend to use this command:

set selfpasswd oldpass <Old Password> passwd <New Password>

This is because the passwords are stored as plain text in the command history.

Instead, use the "set selfpasswd" command.

Important - After you add, configure, or delete features, run the "save config" command to save the settings permanently. Scalable Platforms save the changes automatically.

Two-Factor Authentication for Gaia Login

Watch the Video

Two-Factor Authentication (2FA) adds an additional authentication factor to the Gaia login flow using a time-based authentication app.

When enabled, 2FA protects all logins to the Gaia operating system:

  • Gaia Portal.

  • All CLI shells for a remote login (over SSH or Telnet) and the local login (through a console port or LOM Card):

    For more information about these CLI shells, see Users.

    Important - 2FA protects only the Normal boot mode and the Debug boot mode.

    2FA does not protect the Maintenance boot mode to make sure you can access the operating system to troubleshoot various issues.

    • Gaia Clish (/bin/cli.sh).

    • Gaia gClish (/usr/bin/gclish, /bin/clish) on Scalable Platforms.

    • Expert mode - Bourne Again shell (/bin/bash).

    • C shell (/bin/csh).

    • Turbo C shell (/bin/tcsh).

    • Bourne shell (/bin/sh).

    • Terminal shell from Gaia Portal.

  • RESTful API access.

You can configure the Two-Factor Authentication settings in these ways:

  • In Gaia Portal (described below).

  • In Gaia Clish (described below).

  • With Gaia RESTful API (see Working with Gaia RESTful API > in the API reference, see the chapter "Users Management" > sections "Users" and "Passwords Control").

Enabling Two-Factor Authentication for Specific Users

Part 1 of 2 - Forcing Two-Factor Authentication for specific users

Follow the applicable procedure in Gaia Portal or Gaia Clish / Gaia gClish.

An administrator can force Two-Factor Authentication for specific users.

Each of these users generates the authentication keys during their next login. See Part 2 of 2 below.

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

2

In the navigation tree, click User Management > Users.

3

Select the applicable user.

4

From the top toolbar, click Edit.

5

Select Force to use Two-Factor Authentication.

6

Click OK.

An administrator can enable Two-Factor Authentication for specific users.

Each of these users generates the authentication keys during their next login. See Part 2 of 2 below.

Step

Instructions

1

Connect to the command line.

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must run the applicable commands in Gaia gClish of the applicable Security Group.

2

If your default shell is the Expert mode (/bin/bash), then go to Gaia Clish:

clish

On Scalable Platforms, go to Gaia gClish:

Type gclish and press Enter.

3

Force Two-Factor Authentication for the specific user:

set user <username> force-two-factor-authentication yes

4

Save the changes:

save config

5

Examine the status of the forced Two-Factor Authentication for the user:

show user <username> force-two-factor-authentication

6

Examine the state of Two-Factor Authentication for the user:

show user <username> two-factor-authentication state

An administrator can force Two-Factor Authentication for all users at the same time (including all administrators).

Each user generates the authentication keys during their next login. See Part 2 of 2 below.

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

2

In the navigation tree, click User Management > Password Policy.

3

In the section Two-Factor Authentication, select Force all users to use Two-Factor Authentication.

4

Click Apply.

5

Click Yes to confirm this prompt:

After performing this operation, you will be logged out and will need to log in again.

Are you sure you want to proceed?

An administrator can force Two-Factor Authentication for all users at the same time (including all administrators).

Each user generates the authentication keys during their next login. See Part 2 of 2 below.

Step

Instructions

1

Connect to the command line.

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must run the applicable commands in Gaia gClish of the applicable Security Group.

2

If your default shell is the Expert mode (/bin/bash), then go to Gaia Clish:

clish

On Scalable Platforms, go to Gaia gClish:

Type gclish and press Enter.

3

Force Two-Factor Authentication for all users in Gaia Password Policy:

set password-controls force-two-factor-authentication yes

4

Save the changes:

save config

5

Examine the status of the forced Two-Factor Authentication for all users:

show password-controls force-two-factor-authentication

Part 2 of 2 - First login experience of a user with the forced Two-Factor Authentication (or newly generated authentication keys)

This part describes the user experience in these scenarios:

  • An administrator forced Two-Factor Authentication for a specific user or all users, and the user did not generate Two-Factor Authentication keys yet.

  • An administrator generated new Two-Factor Authentication keys for a specific user.

This is the experience of the user during their next login in Gaia Portal:

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

2

Enter your username and press the Enter key (or click Next).

3

Enter your password and press the Enter key (or click Login).

4

Click Set Up.

Follow the instructions on the screen to configure an account in the 2FA app on your mobile device.

5

Install a supported 2FA time-based app on your mobile device. See sk181854.

6

In the 2FA app:

  1. Tap the applicable button to add a new account.

  2. Tap the applicable account type option.

  3. Scan the QR code you see in Gaia Portal.

    Alternatively, use the pre-shared key you see in Gaia Portal.

7

Click Next.

8

Save the 2FA backup keys.

You can copy them from Gaia Portal or click Download backup keys.

Warnings:

  • Gaia Portal shows these backup keys only one time.

    You can find these backup keys in this file:

    /etc/2fa_keys/<username>/.google_authenticator

  • Keep these backup keys in a secure location.

  • Do not share these backup keys with unauthorized personnel.

9

Click Done.

10

If you forgot to save the 2FA backup keys, then click Cancel to go to the previous page.

If you already saved the 2FA backup keys, then click OK.

This is the experience of the specific user during their next login in CLI (regardless of their default shell):

Step

Instructions

1

Connect to the command line.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must run the applicable commands in Gaia gClish of the applicable Security Group.

2

Enter your username and password.

3

In this prompt, enter "y" and press the Enter key:

Your security administrator requires you to use Two-Factor Authentication. Do you want to proceed? (y/n):

4

CLI shell shows this information (and then shows the shell prompt):

  • QR Code to create an account in the 2FA app

  • Secret key to create an account in the 2FA app

  • Emergency scratch codes (2FA backup keys)

    Warnings:

    • Gaia Clish shows these backup keys only one time.

      You can find these backup keys in this file:

      /etc/2fa_keys/<username>/.google_authenticator

    • Keep these backup keys in a secure location.

    • Do not share these backup keys with unauthorized personnel.

5

Install a supported 2FA time-based app on your mobile device. See sk181854.

6

In the 2FA app:

  1. Tap the applicable button to add a new account.

  2. Tap the applicable account type option.

  3. Scan the QR code you see in Gaia Clish.

    Alternatively, use the secret key you see in Gaia Clish.

Enabling Two-Factor Authentication for the Current User

A user with the required permissions can enable Two-Factor Authentication for their username in the current session.

The current user generates the authentication keys during the current session.

Warning - If you started this procedure, but changed your mind in the middle, then you must not close Gaia Portal.

If you just close Gaia Portal or let the session time out, then your user will be locked out without any possibility to log in.

You must do one of these:

  • Complete the procedure.

  • Click Cancel > enter your Gaia login password > click OK > click Yes to confirm.

    This completely disables Two-Factor Authentication.

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

2

In the navigation tree, click User Management > Authentication.

3

In the section Two-Factor Authentication Settings, click Enable Two-Factor Authentication.

4

Install a supported 2FA time-based app on your mobile device. See sk181854.

5

In the 2FA app:

  1. Tap the applicable button to add a new account.

  2. Tap the applicable account type option.

  3. Scan the QR code you see in Gaia Portal.

    Alternatively, use the pre-shared key you see in Gaia Portal.

6

Click Next.

7

Save the 2FA backup keys.

You can copy them from Gaia Portal or click Download backup keys.

Warnings:

  • Gaia Portal shows these backup keys only one time.

    You can find these backup keys in this file:

    /etc/2fa_keys/<username>/.google_authenticator

  • Keep these backup keys in a secure location.

  • Do not share these backup keys with unauthorized personnel.

8

Click Done.

9

If you forgot to save the 2FA backup keys, then click Cancel to go to the previous page.

If you already saved the 2FA backup keys, then click OK.

A user with the required permissions can enable Two-Factor Authentication for their username in the current session.

The current user generates the authentication keys during their next login.

Step

Instructions

1

Connect to the command line.

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must run the applicable commands in Gaia gClish of the applicable Security Group.

2

If your default shell is the Expert mode (/bin/bash), then go to Gaia Clish:

clish

On Scalable Platforms, go to Gaia gClish:

Type gclish and press Enter.

3

Force Two-Factor Authentication for the currently logged in user:

set two-factor-authentication state on

4

Save the changes:

save config

5

Examine the status of the forced Two-Factor Authentication for the user:

show user <username> force-two-factor-authentication

6

Examine the state of the Two-Factor Authentication for the currently logged in user:

show two-factor-authentication state

Generating New Two-Factor Authentication Keys

An administrator can generate new 2FA keys for a specific user.

Follow the applicable procedure in Gaia Portal or Gaia Clish / Gaia gClish.

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

2

In the navigation tree, click User Management > Users.

3

Select the user.

You can select your username of a different username.

4

From the top toolbar, click Regenerate Key.

5

Click OK to confirm.

6

When a user connects to the Gaia operating system the next time, the user must:

  1. Enter their username.

  2. Enter their password.

  3. Follow the instructions on the screen to continue:

    • In Gaia Portal, click Set Up.

    • In Gaia Clish, enter "y" in the prompt.

  4. In the 2FA app, remove the current account.

  5. In the 2FA app, add a new account.

Step

Instructions

1

Connect to the command line.

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must run the applicable commands in Gaia gClish of the applicable Security Group.

2

If your default shell is the Expert mode (/bin/bash), then go to Gaia Clish:

clish

On Scalable Platforms, go to Gaia gClish:

Type gclish and press Enter.

3

Force the generation of new Two-Factor Authentication keys for the specific user:

set user <username> regenerate-two-factor-authentication

4

Save the changes:

save config

An administrator can generate new 2FA keys for their username and force the configuration of the 2FA keys during the current login.

Warning - If you started this procedure, but changed your mind in the middle, then you must not close Gaia Portal.

If you just close Gaia Portal or let the session time out, then users will be locked out without any possibility to log in.

You must do one of these:

  • Complete the procedure.

  • Click Cancel > enter your Gaia login password > click OK > click Yes to confirm.

    This completely disables Two-Factor Authentication.

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Log in with your credentials.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

2

In the navigation tree, click User Management > Authentication.

Refer to the section Two-Factor Authentication Settings.

3

Click Regenerate the Authentication Key.

4

Enter your Gaia login password.

5

In the 2FA app:

  1. Delete the current account.

  2. Tap the applicable button to add a new account.

  3. Tap the applicable account type option.

  4. Scan the QR code you see in Gaia Portal.

6

Click Next.

7

Save the 2FA backup keys.

You can copy them from Gaia Portal or click Download backup keys.

Warnings:

  • Gaia Portal shows these backup keys only one time.

    You can find these backup keys in this file:

    /etc/2fa_keys/<username>/.google_authenticator

  • Keep these backup keys in a secure location.

  • Do not share these backup keys with unauthorized personnel.

8

Click Done.

9

If you forgot to save the 2FA backup keys, then click Cancel to go to the previous page.

If you already saved the 2FA backup keys, then click OK.

Disabling Two-Factor Authentication for Specific Users

Follow the applicable procedure in Gaia Portal or Gaia Clish / Gaia gClish.

Part 1 of 2 - Disabling the forced Two-Factor Authentication for a specific user

An administrator can disable the forced Two-Factor Authentication for specific users.

The specific user must manually disable Two-Factor Authentication.

Note - This is possible only if Two-Factor Authentication is not forced for all users by the Gaia Password Policy.

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

2

In the navigation tree, click User Management > Users.

3

Select the applicable user.

4

From the top toolbar, click Edit.

5

Clear Force to use Two-Factor Authentication.

6

Click OK.

An administrator can disable the forced Two-Factor Authentication for specific users.

The specific user must manually disable Two-Factor Authentication.

Note - This is possible only if Two-Factor Authentication is not forced for all users by the Gaia Password Policy.

Step

Instructions

1

Connect to the command line.

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must run the applicable commands in Gaia gClish of the applicable Security Group.

2

If your default shell is the Expert mode (/bin/bash), then go to Gaia Clish:

clish

On Scalable Platforms, go to Gaia gClish:

Type gclish and press Enter.

3

Disable Two-Factor Authentication for the specific user:

set user <username> force-two-factor-authentication no

4

Save the changes:

save config

5

Examine the status of the forced Two-Factor Authentication for the user:

show user <username> force-two-factor-authentication

6

Examine the state of the Two-Factor Authentication for the user:

show user <username> two-factor-authentication state

Part 2 of 2 - Disabling Two-Factor Authentication by the specific user

Follow the applicable procedure in the section Disabling Two-Factor Authentication for the Current User.

Disabling Two-Factor Authentication for All Users

Follow the applicable procedure in Gaia Portal or Gaia Clish / Gaia gClish.

Part 1 of 2 - Disabling the forced Two-Factor Authentication for all users

An administrator can disable the forced Two-Factor Authentication for all users.

Each user must manually disable Two-Factor Authentication.

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

2

In the navigation tree, click User Management > Password Policy.

3

In the section Two-Factor Authentication, clear Force all users to use Two-Factor Authentication.

4

Click Apply.

5

In the navigation tree, click User Management > Users.

6

For each user with the state Enabled in the column Two-Factor Authentication:

  1. Select the user.

  2. From the top toolbar, click Edit.

  3. Clear Force to use Two-Factor Authentication.

  4. Click OK.

An administrator can disable the forced Two-Factor Authentication for all users.

Each user must manually disable Two-Factor Authentication.

Step

Instructions

1

Connect to the command line.

Log in with credentials of an administrator.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must run the applicable commands in Gaia gClish of the applicable Security Group.

2

If your default shell is the Expert mode (/bin/bash), then go to Gaia Clish:

clish

On Scalable Platforms, go to Gaia gClish:

Type gclish and press Enter.

3

Disable Two-Factor Authentication for all users in Gaia Password Policy:

set password-controls force-two-factor-authentication no

4

Save the changes:

save config

5

Examine the list of users:

show users

6

Examine the state of Two-Factor Authentication for each user:

show user <username> two-factor-authentication state

7

Disable Two-Factor Authentication for each user, for whom it is currently enabled:

set user <username> force-two-factor-authentication no

8

Save the changes:

save config

Part 2 of 2 - Disabling Two-Factor Authentication by the specific user

Follow the applicable procedure in the section Disabling Two-Factor Authentication for the Current User.

Disabling Two-Factor Authentication for the Current User

Follow the applicable procedure in Gaia Portal or Gaia Clish / Gaia gClish.

A user can disable Two-Factor Authentication for their username in the current session.

Note - This is possible only if Two-Factor Authentication is not forced in these places:

  • For all users by the Gaia Password Policy.

  • For the current user in their user object.

Step

Instructions

1

With a web browser, connect to Gaia Portal at:

https://<IP address of Gaia Management Interface>

If you changed the default port of Gaia Portal from 443, then you must also enter it (https://<IP address>:<Port>).

Log in with your credentials and a Two-Factor Authentication key.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must connect to the Gaia Portal of the applicable Security Group.

2

In the navigation tree, click User Management > Authentication.

3

In the section Two-Factor Authentication Settings, click Disable Two-Factor Authentication.

4

Enter your Gaia login password.

5

Click OK.

6

Click Yes to confirm.

7

In the navigation tree, click User Management > Users.

8

In the row for your username, the column Two-Factor Authentication must show Disabled.

A user can disable Two-Factor Authentication for their username in the current session.

Note - This is possible only if Two-Factor Authentication is not forced in these places:

  • For all users by the Gaia Password Policy.

  • For the current user in their user object.

Step

Instructions

1

Connect to the command line.

Log in with your credentials and a Two-Factor Authentication key.

Important - On Scalable Platforms (ElasticXL, Maestro, and Chassis), you must run the applicable commands in Gaia gClish of the applicable Security Group.

2

If your default shell is the Expert mode (/bin/bash), then go to Gaia Clish:

clish

On Scalable Platforms, go to Gaia gClish:

Type gclish and press Enter.

3

Examine the status of the forced Two-Factor Authentication for the user:

show user <your username> force-two-factor-authentication

4

Examine the state of the Two-Factor Authentication for the currently logged in user:

show two-factor-authentication state

5

Disable Two-Factor Authentication for the currently logged in user:

set two-factor-authentication state off

6

Save the changes:

save config

Gaia Clish / Gaia gClish Syntax for Two-Factor Authentication

The applicable procedures appear above in the corresponding sections.

Syntax to force Two-Factor Authentication for specific users:

set user <username> force-two-factor-authentication {yes | no}

show user <username> force-two-factor-authentication

show user <username> two-factor-authentication state

Syntax to force Two-Factor Authentication for all users:

set password-controls force-two-factor-authentication {yes | no}

show password-controls force-two-factor-authentication

Syntax to enable Two-Factor Authentication for the currently logged-in user:

set two-factor-authentication state {on | off}

show two-factor-authentication state

Syntax to generate new Two-Factor Authentication keys for a specific user (during the next login):

set user <username> regenerate-two-factor-authentication

Troubleshooting

These steps are available:

Scenario

Available Steps

There is at least one Gaia administrator who can log in

  • An administrator needs to generate new Two-Factor Authentication keys for the affected user.

  • An administrator needs to boot into the Maintenance boot mode and delete this file for the affected user:

    /etc/2fa_keys/<username>/.google_authenticator

There are no Gaia administrators who can log in

  • Restore the Gaia operating system to Factory Defaults from the Boot Menu.

  • Perform a clean install from a bootable device. See sk65205.