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


AuthApiKeyPlain

Type: object
No Additional Properties

Mechanism

Type: const
Specific value: "API_KEY_PLAIN"

Username

Type: string

Api Key

Type: string

AuthCommonOptions

Type: object Default: {"user_info": true}
No Additional Properties

User Info

Type: boolean Default: true

AuthPasswordPlain

Type: object
No Additional Properties

Mechanism

Type: const
Specific value: "PASSWORD_PLAIN"

Username

Type: string

Password

Type: string

AuthCommonOptions

Type: object Default: {"user_info": true}
No Additional Properties

User Info

Type: boolean Default: true

AuthTokenPlain

Type: object
No Additional Properties

Mechanism

Type: const
Specific value: "TOKEN_PLAIN"

Token

Type: string

AuthCommonOptions

Type: object Default: {"user_info": true}
No Additional Properties

User Info

Type: boolean Default: true

AuthOTPToken

Type: object
No Additional Properties

Mechanism

Type: const
Specific value: "OTP_TOKEN"

Otp Token

Type: string

AuthCommonOptions

Type: object Default: {"user_info": true}
No Additional Properties

User Info

Type: boolean Default: true

Result


AuthRespSuccess

Type: object
No Additional Properties

Response Type

Type: const
Specific value: "SUCCESS"


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 list 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

boolean value indicating whether the account is local to TrueNAS or provided by a directory service.

Attributes

Type: object

Two Factor Config

Type: object

Privilege

Type: object

Account Attributes

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

Authenticator

Type: enum (of string)
Must be one of:
  • "LEVEL_1"
  • "LEVEL_2"

AuthRespAuthErr

Type: object
No Additional Properties

Response Type

Type: const
Specific value: "AUTH_ERR"

AuthRespExpired

Type: object
No Additional Properties

Response Type

Type: const
Specific value: "EXPIRED"

AuthRespOTPRequired

Type: object
No Additional Properties

Response Type

Type: const
Specific value: "OTP_REQUIRED"

Username

Type: string

AuthRespAuthRedirect

Type: object
No Additional Properties

Response Type

Type: const
Specific value: "REDIRECT"

Urls

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


Required roles: