auth.login_ex

Authenticate using one of a variety of mechanisms

NOTE: mechanisms with a _PLAIN suffix indicate that they involve passing plain-text passwords or password-equivalent strings and should not be used on untrusted / insecure transport. Available mechanisms will be expanded in future releases.

params: This takes a single argument consistning of a JSON object with the following keys:

mechanism: the mechanism by which to authenticate to the backend the exact parameters to use vary by mechanism and are described below

PASSWORD_PLAIN username: username with which to authenticate password: password with which to authenticate login_options: dictionary with additional authentication options

API_KEY_PLAIN username: username with which to authenticate api_key: API key string login_options: dictionary with additional authentication options

AUTH_TOKEN_PLAIN token: authentication token string login_options: dictionary with additional authentication options

OTP_TOKEN otp_token: one-time password token. This is only permitted if a previous auth.login_ex call responded with “OTP_REQUIRED”.

login_options user_info: boolean - include auth.me output in successful responses.

raises: CallError: a middleware CallError may be raised in the following circumstances.

  • An multistep challenge-response authentication mechanism is being used and the specified mechanism does not match the expected next step for authentication. In this case the errno will be set to EBUSY.

  • OTP_TOKEN mechanism was passed without an explicit request from a previous authentication step. In this case the errno will be set to EINVAL.

  • Current authenticator assurance level prohibits the use of the specified authentication mechanism. In this case the errno will be set to EOPNOTSUPP.

returns: JSON object containing the following keys:

response_type: string indicating the results of the current authentication mechanism. This is used to inform client of nature of authentication error or whether further action will be required in order to complete authentication.

<additional keys per response_type>

Notes about response types:

SUCCESS: additional key: user_info: includes auth.me output for the resulting authenticated credentials.

OTP_REQUIRED additional key: username: normalized username of user who must provide an OTP token.

AUTH_ERR Generic authentication error corresponds to PAM_AUTH_ERR and PAM_USER_UNKOWN from libpam. This may be returned if the account does not exist or if the credential is incorrect.

EXPIRED The specified credential is expired and not suitable for authentication.

REDIRECT Authentication must be performed on different server.

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: login_data

login_data


Authentication data specifying mechanism and credentials.

AuthApiKeyPlain

Type: object
No Additional Properties

Mechanism

Type: const

Authentication mechanism identifier for plain API key authentication.

Must be one of:
  • "API_KEY_PLAIN"
Specific value: "API_KEY_PLAIN"

Username

Type: string

Username associated with the API key.

Api Key

Type: string

API key for authentication.

AuthCommonOptions

Type: object Default: {"user_info": true}

Additional options for the authentication process.

 No Additional Properties

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

AuthPasswordPlain

Type: object
No Additional Properties

Mechanism

Type: const

Authentication mechanism identifier for plain password authentication.

Must be one of:
  • "PASSWORD_PLAIN"
Specific value: "PASSWORD_PLAIN"

Username

Type: string

Username for authentication.

Password

Type: string

Password for authentication.

AuthCommonOptions

Type: object Default: {"user_info": true}

Additional options for the authentication process.

 No Additional Properties

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

AuthTokenPlain

Type: object
No Additional Properties

Mechanism

Type: const

Authentication mechanism type for plain token login.

Must be one of:
  • "TOKEN_PLAIN"
Specific value: "TOKEN_PLAIN"

Token

Type: string

Authentication token (masked for security).

AuthCommonOptions

Type: object Default: {"user_info": true}

Common authentication options and settings.

 No Additional Properties

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

AuthOTPToken

Type: object
No Additional Properties

Mechanism

Type: const

Authentication mechanism identifier for one-time password tokens.

Must be one of:
  • "OTP_TOKEN"
Specific value: "OTP_TOKEN"

Otp Token

Type: string

One-time password token for authentication.

AuthCommonOptions

Type: object Default: {"user_info": true}

Additional options for the authentication process.

 No Additional Properties

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

Result


Authentication response indicating success, failure, or additional steps required.

AuthRespSuccess

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating successful login.

Must be one of:
  • "SUCCESS"
Specific value: "SUCCESS"


Authenticated user information or null if not available.

AuthUserInfo

Type: object
No Additional Properties

Pw Name

Type: string

Name of the user.

Pw Gecos

Type: string

Full username or comment field.

Pw Dir

Type: string

User home directory.

Pw Shell

Type: string

User command line interpreter.

Pw Uid

Type: integer

Numerical user ID of the user.

Pw Gid

Type: integer

Numerical group id for the user's primary group.

Grouplist


Optional array of group IDs for groups of which this account is a member. If get_groups is not specified, this value will be null.

Type: array of integer
No Additional Items
Each item of this array must be:
Type: integer
Type: null

Sid


Optional SID value for the account that is present if sid_info is specified in payload.

Type: string
Type: null

Source

Type: enum (of string)

The source for the user account.

Must be one of:
  • "LOCAL"
  • "ACTIVEDIRECTORY"
  • "LDAP"

Local

Type: boolean

The account is local to TrueNAS or provided by a directory service.

Attributes

Type: object

Custom user attributes and metadata.

Two Factor Config

Type: object

Two-factor authentication configuration for the user.

Privilege

Type: object

User privilege and role information.

Account Attributes

Type: array of string

Array of account attribute names available for this user.

 No Additional Items
Each item of this array must be:
Type: string
Type: null

Authenticator

Type: enum (of string)

Authentication level achieved (LEVEL1 for password, LEVEL2 for two-factor).

Must be one of:
  • "LEVEL_1"
  • "LEVEL_2"

AuthRespAuthErr

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating authentication failure.

Must be one of:
  • "AUTH_ERR"
Specific value: "AUTH_ERR"

AuthRespExpired

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating the session or token has expired.

Must be one of:
  • "EXPIRED"
Specific value: "EXPIRED"

AuthRespOTPRequired

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating one-time password is required.

Must be one of:
  • "OTP_REQUIRED"
Specific value: "OTP_REQUIRED"

Username

Type: string

Username for which OTP is required.

AuthRespAuthRedirect

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating redirect is required.

Must be one of:
  • "REDIRECT"
Specific value: "REDIRECT"

Urls

Type: array of string

Array of URLs to redirect to for authentication completion.

 No Additional Items
Each item of this array must be:
Type: string


Required roles: