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

Call parameters

Type: array
No Additional Items

Tuple Validation

Parameter 1: login_data

login_data

Authentication data specifying mechanism and credentials.

One of

• AuthApiKeyPlain
• AuthPasswordPlain
• AuthTokenPlain
• AuthOTPToken

AuthApiKeyPlain

Type: object
No Additional Properties

mechanism Required

Mechanism

Type: const

Authentication mechanism identifier for plain API key authentication.

Specific value: "API_KEY_PLAIN"

username Required

Username

Type: string

Username associated with the API key.

api_key Required

Api Key

Type: string

API key for authentication.

login_options

AuthCommonOptions

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

Additional options for the authentication process.

No Additional Properties

user_info

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

AuthPasswordPlain

Type: object
No Additional Properties

mechanism Required

Mechanism

Type: const

Authentication mechanism identifier for plain password authentication.

Specific value: "PASSWORD_PLAIN"

username Required

Username

Type: string

Username for authentication.

password Required

Password

Type: string

Password for authentication.

login_options

AuthCommonOptions

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

Additional options for the authentication process.

No Additional Properties

user_info

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

AuthTokenPlain

Type: object
No Additional Properties

mechanism Required

Mechanism

Type: const

Authentication mechanism type for plain token login.

Specific value: "TOKEN_PLAIN"

token Required

Token

Type: string

Authentication token (masked for security).

login_options

AuthCommonOptions

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

Common authentication options and settings.

No Additional Properties

user_info

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

AuthOTPToken

Type: object
No Additional Properties

mechanism Required

Mechanism

Type: const

Authentication mechanism identifier for one-time password tokens.

Specific value: "OTP_TOKEN"

otp_token Required

Otp Token

Type: string

One-time password token for authentication.

login_options

AuthCommonOptions

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

Additional options for the authentication process.

No Additional Properties

user_info

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

Return value

Result

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

One of

• AuthRespSuccess
• AuthRespAuthErr
• AuthRespExpired
• AuthRespOTPRequired
• AuthRespAuthRedirect

AuthRespSuccess

Type: object
No Additional Properties

response_type Required

Response Type

Type: const

Authentication response type indicating successful login.

Specific value: "SUCCESS"

user_info Required

Authenticated user information or null if not available.

Any of

• AuthUserInfo
• Option 2

AuthUserInfo

Type: object
No Additional Properties

pw_name Required

Pw Name

Type: string

Name of the user.

pw_gecos Required

Pw Gecos

Type: string

Full username or comment field.

pw_dir Required

Pw Dir

Type: string

User home directory.

pw_shell Required

Pw Shell

Type: string

User command line interpreter.

pw_uid Required

Pw Uid

Type: integer

Numerical user ID of the user.

pw_gid Required

Pw Gid

Type: integer

Numerical group id for the user's primary group.

grouplist Required

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.

Any of

• Option 1
• Option 2

Type: array of integer
No Additional Items

Each item of this array must be:

Type: integer

Type: null

sid Required

Sid

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

Any of

• Option 1
• Option 2

Type: string

Type: null

source Required

Source

Type: enum (of string)

The source for the user account.

Must be one of:

• "LOCAL"
• "ACTIVEDIRECTORY"
• "LDAP"

local Required

Local

Type: boolean

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

attributes Required

Attributes

Type: object

Custom user attributes and metadata.

two_factor_config Required

Two Factor Config

Type: object

Two-factor authentication configuration for the user.

privilege Required

Privilege

Type: object

User privilege and role information.

account_attributes Required

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 Required

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 Required

Response Type

Type: const

Authentication response type indicating authentication failure.

Specific value: "AUTH_ERR"

AuthRespExpired

Type: object
No Additional Properties

response_type Required

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 Required

Response Type

Type: const

Authentication response type indicating one-time password is required.

Specific value: "OTP_REQUIRED"

username Required

Username

Type: string

Username for which OTP is required.

AuthRespAuthRedirect

Type: object
No Additional Properties

response_type Required

Response Type

Type: const

Authentication response type indicating redirect is required.

Specific value: "REDIRECT"

urls Required

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: