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


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}

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.

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}

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.

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}

Common authentication options and settings.

 No Additional Properties

User Info

Type: boolean Default: true

Whether to include detailed user information in the authentication response.

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}

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.

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 support is also a planned enhancement of the authentication
mechanism.

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"

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


Required roles: