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


AuthApiKeyPlain

Type: object
No Additional Properties

Mechanism

Type: const
Must be one of:
  • "API_KEY_PLAIN"
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
Must be one of:
  • "PASSWORD_PLAIN"
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
Must be one of:
  • "TOKEN_PLAIN"
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
Must be one of:
  • "OTP_TOKEN"
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
Must be one of:
  • "SUCCESS"
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
Must be one of:
  • "AUTH_ERR"
Specific value: "AUTH_ERR"

AuthRespExpired

Type: object
No Additional Properties

Response Type

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

AuthRespOTPRequired

Type: object
No Additional Properties

Response Type

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

Username

Type: string

AuthRespAuthRedirect

Type: object
No Additional Properties

Response Type

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

Urls

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


Required roles: