# 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. reconnect_token: boolean - include a reconnect token 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 keys: user_info: includes auth.me output for the resulting authenticated credentials. reconnect_token: token that can be used to reauthenticate if the websocket session is interrupted, or null if not requested or not supported by the credential type.

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

## Any of

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

## Any of

#### AuthRespSuccess

Type: object
No Additional Properties

##

#### Response Type

Type: const
Specific value: `"SUCCESS"`

##

## Any of

#### 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.

## Any of

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.

## Any of

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: