TrueNAS SCALE Documentation Archive
This content follows the TrueNAS SCALE 22.12 (Bluefin) releases. Archival documentation is provided for reference only and not actively maintained.
Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.

Auth

4 minute read.

Last Modified 2024-03-19 08:47 EDT

The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!

Auth Commands

The auth namespace has five commands and four child namespaces and is based on functions found in the SCALE API and web UI. It provides access to authentication methods for the logged-in user and a method to generate an access token for web UI session through the five auth commands. The four child namespaces have their own commands.

You can enter commands from the main CLI prompt or from an auth namespace prompt.

Check_User Command

The check_user and check_password commands verify the logged-in credentials.

Verify Username and Password

The check_user command has two required options, username and password to include in the command string. Command returns true if the values entered for the username and password are correct.

From the CLI prompt, enter:

auth check_user username=name password=password

From the auth prompt, enter:

check_user username=name password=password

Where:

username is the name assigned to the user logged in. For example, if the admin user is logged in and named admin, enter admin as the value.
password is the password assigned to the user logged in.

Command Example

auth check_user username=admin password=securePassw0rd
true

Check_Password Command

The check_password and check_user commands verify the logged-in user credentials.

Verify Username and Password

The check_password command has two required options, username and password to include in the command string. Command returns true if the values entered for the username and password are correct.

From the CLI prompt, enter:

auth check_password username=name password=password

From the auth prompt, enter:

check_password username=name password=password

Where:

username is the name assigned to the user logged in. For example, if the admin user is logged in and named admin, enter admin as the value.
password is the password assigned to the user logged in.

Command Example

auth check_password username=admin password=securePassw0rd
true

Generate_Token Command

The generate_token command generates an authentication token to use for access. The setting determines when the current session expires.

Generate Access Token

The generate_token command has three required options, ttl, attrs, and match_origin to include in the command string. Command returns an authentication token.

From the CLI prompt, enter:

auth generate_token ttl=value attrs= {} match_origin=value

From the auth namespace prompt, enter:

generate_token ttl=value attrs= {} match_origin=value

where:

ttl= represents the time to live (ttl) value is in seconds. Values are either 600 or null.
600equates to an idle authentication session lasting 10 minutes before the token expires and the user must log back into the UI. null means the session does not expire, and is not recommended as a best practice for system security.
attrs= {} represents attribute options for the token. {} is the default. (Optional) Enter options in the curly brackets to define specific values.
match_origin=value represents a boolean (true/false) value.

Command Example

auth generate_token ttl=600 atters={} match_origin=true
SER140235708avernneruou390854RMV2357098-AERV235Wbyo

Me Command

The me command returns password, user and group information about the currently logged-in user.

Generate Access Token

The me command does not require entering additional options or arguments. Enter the command, then press Enter.

From the CLI prompt, enter:

auth me

From the auth namespace prompt, enter: me

Output includes:

Property	Description
pw_name	Displays the logged-in user name. For example, admin.
pw_uid	Displays the user ID (UID) number for the logged-in user. For example, 3000.
pw_gid	Displays the group ID (GID) number for the logged-in user. For example, 3000.
pw_gecos	Displays the record in the /etc/passwd file, which is general information about the account or user. For example, for the admin user.
pw_dir	Displays the password or home directory for the logged-in user. For example, mnt/tank/homedir.
pw_shell	Displays the logged-in user shell setting. For example, /usr/bin/bash displays when the Shell setting on the Add User or Edit User screen is set to bash.

Command Example

auth me
+----------+-------------------+
|  pw_name | admin             |
|   pw_uid | 3000              |
|   pw-gid | 3000              |
| pw_gecos | admin             |
|   pw-dir | /mnt/tank/homedir |
| pw-shell | /usr/bin/bash     |
+----------+-------------------+

Two-Factor_Auth Command

The two_factor_auth command returns the state of two-factor authentication for the logged-in user.

Verify Two Factor Authentication Setting

The two_factor_auth command does not require entering options. Enter the command, then press Enter.

From the CLI prompt, enter:

auth two_factor_auth

From the auth namespace prompt, enter:

two_factor_auth

Command Example

auth two_factor_auth
false

Auth Child Namespace Articles

The following articles provide information on auth child authentication namespaces:

API_Key: Provides information about the auth api_key namespace in the TrueNAS CLI. Includes command syntax and common commands.

Privilege: Provides information about the auth privilege namespace in the TrueNAS CLI. Includes command syntax and common commands.

Sessions: Provides information about the auth sessions namespace in the TrueNAS CLI. Includes command syntax and common commands.

Two_Factor: Provides information about the auth two_factor namespace in the TrueNAS CLI. Includes command syntax and common commands.