auth.login_ex

Authenticate using one of a variety of mechanisms.

The mechanism is selected by the mechanism field of the request, and the set of supported mechanisms will be expanded in future releases.

Warning

Mechanisms with a _PLAIN suffix involve passing plain-text passwords or password-equivalent strings and should not be used over untrusted or insecure transport.

The response_type of the result indicates the outcome of the current authentication step and whether further action is required to complete authentication:

  • SUCCESS – authentication completed and a session was established.

  • OTP_REQUIRED – the account requires a one-time password; the client must continue authentication by submitting the token via the OTP_TOKEN mechanism.

  • AUTH_ERR – generic authentication failure corresponding to PAM_AUTH_ERR and PAM_USER_UNKNOWN from libpam. Returned when the account does not exist or the credential is incorrect.

  • EXPIRED – the supplied credential is expired and not suitable for authentication.

  • REDIRECT – authentication must be performed on a different server.

A JSON-RPC error response (code -32001, Method call error) is returned instead of a result in the following cases:

  • a multistep challenge-response mechanism is in progress and the supplied mechanism does not match the expected next step (errno EBUSY)

  • the OTP_TOKEN mechanism is used without a preceding step having requested it (errno EINVAL)

  • the current authenticator assurance level prohibits the supplied mechanism (errno EOPNOTSUPP)

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.

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, "reconnect_token": false }

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.

Reconnect Token

Type: boolean Default: false

Whether to include a reauthentication token in the authentication response. The ttl for the generated token depends on the TrueNAS webui setting for preferences->lifetime, with a default value of 600 seconds.

AuthPasswordPlain

Type: object
No Additional Properties

Mechanism

Type: const

Authentication mechanism identifier for plain password authentication.

Specific value: "PASSWORD_PLAIN"

Username

Type: string

Username for authentication.

Password

Type: string

Password for authentication.

AuthCommonOptions

Type: object
Default:
{ "user_info": true, "reconnect_token": false }

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.

Reconnect Token

Type: boolean Default: false

Whether to include a reauthentication token in the authentication response. The ttl for the generated token depends on the TrueNAS webui setting for preferences->lifetime, with a default value of 600 seconds.

AuthTokenPlain

Type: object
No Additional Properties

Mechanism

Type: const

Authentication mechanism type for plain token login.

Specific value: "TOKEN_PLAIN"

Token

Type: string

Authentication token (masked for security).

AuthCommonOptions

Type: object
Default:
{ "user_info": true, "reconnect_token": false }

Common authentication options and settings.

 No Additional Properties

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

Reconnect Token

Type: boolean Default: false

Whether to include a reauthentication token in the authentication response. The ttl for the generated token depends on the TrueNAS webui setting for preferences->lifetime, with a default value of 600 seconds.

AuthOTPToken

Type: object
No Additional Properties

Mechanism

Type: const

Authentication mechanism identifier for one-time password tokens.

Specific value: "OTP_TOKEN"

Otp Token

Type: string

One-time password token for authentication.

AuthCommonOptions

Type: object
Default:
{ "user_info": true, "reconnect_token": false }

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.

Reconnect Token

Type: boolean Default: false

Whether to include a reauthentication token in the authentication response. The ttl for the generated token depends on the TrueNAS webui setting for preferences->lifetime, with a default value of 600 seconds.

AuthSCRAM

Type: object
No Additional Properties

Mechanism

Type: const

Authentication mechanism that implements SHA512-based RFC5802 authentication. The authentication mechanism provides replay resistence and capability for mutual validation of server and client sessions.

The authentication mechanism is currently limited to API key credentials, but at a future point will be expanded to cover local user authentication.

Channel binding (RFC 5929 tls-server-end-point) is supported and negotiated per exchange. A client that requires it sends a p=tls-server-end-point gs2 header over a TLS connection (see rfc_str) and the server verifies it against the certificate it serves; binding is only honored over TLS and remains optional, so clients that do not request it still authenticate.

C and python libraries to for managing the client-side portion of the authentication exchanges are provided at https://github.com/truenas/truenas_scram.

Specific value: "SCRAM"

Scram Type

Type: enum (of string)

Scram message type from client. The scram types indicate the message type that is represented by the rfc_str field. CLIENTFIRSTMESSAGE - this corresponds with the client-first-message as defined in RFC5802. CLIENTFINALMESSAGE - this corresponds with the client-final-message as defined in RFC5802.

Must be one of:
  • "CLIENT_FIRST_MESSAGE"
  • "CLIENT_FINAL_MESSAGE"

Rfc Str

Type: string

This field contains the SCRAM authentication exchange message as defined in RFC5802. The expected format and contents depends on the scram_type. CLIENTFIRSTMESSAGE: n,,n=user:10,r=fyko+d2lbbFgONRv9qkxdawL The n,, component indicates that client does not support channel bindings. n=user:10 specifies the username and API key id (separated by : character). r=fyko+d2lbbFgONRv9qkxdawL specifies a base64-encoded nonce generated client-side. CLIENTFINALMESSAGE: c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts= c=biws contains channel binding information. In this example it's the base64-encoded string n,, (no channel binding support). r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j contains the combined client and server nonce as returned by the response to the CLIENTFIRSTMESSAGE. p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts= contains the base64-encoded client proof generated based on client-side key material and client + server nonce.
Examples:

"n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL"

"c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts="

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.

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"

Reconnect Token


Single-use token that can be used to reauthenticate to the truenas server in case websocket session is interrupted. This will be null in the following situations:

1) The initiating authentication request set reconnect_token to false (default).
2) The user authenticated via a one-time password, which does not support reconnect token creation.

Type: string
Type: null

AuthRespAuthErr

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating authentication failure.

Specific value: "AUTH_ERR"

AuthRespExpired

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating the session or token has expired.

Specific value: "EXPIRED"

AuthRespOTPRequired

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating one-time password is 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.

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

AuthRespScram

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating a SCRAM server response.

Specific value: "SCRAM_RESPONSE"

Scram Type

Type: enum (of string)

The type of server response. The SERVERFIRSTRESPONSE will contain nonce, salt, and iterations. The SERVERFINALRESPONSE will contain the server verification proof for client mutual validation.

Must be one of:
  • "SERVER_FIRST_RESPONSE"
  • "SERVER_FINAL_RESPONSE"

Rfc Str

Type: string

Server authentication response containing string per RFC5802.
Examples:

"r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,s=QSXCR+Q6sek8bf92,i=500000"

"v=rmF9pqV8S7suAoZWja4dJRkFsKQ="


Authenticated user information on SERVERFINALRESPONSE or null on SERVERFIRSTRESPONSE.

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

AuthRespDenied

Type: object
No Additional Properties

Response Type

Type: const

Authentication response type indicating that the credential lacks API access.

Specific value: "DENIED"


Required roles: