# Module cartridge.auth

Administrators authentication and authorization.

## Local Functions

### set_enabled (enabled)

Allow or deny unauthenticated access to the administrator’s page. (Changed in v0.11)

This function affects only the current instance. It can’t be used after the cluster was bootstrapped. To modify clusterwide config use `set_params` instead.

Parameters:

- enabled: (boolean)

Returns:

(boolean) true

Or

(nil)

(table) Error description

### get_enabled ()

Check if unauthenticated access is forbidden. (Added in v0.7)

Returns:

(boolean) enabled

### init ()

Initialize the authentication HTTP API.

Set up `login` and `logout` HTTP endpoints.

### set_callbacks (callbacks)

Set authentication callbacks.

Parameters:

- callbacks:

  - add_user: (function)

  - get_user: (function)

  - edit_user: (function)

  - list_users: (function)

  - remove_user: (function)

  - check_password: (function)

Returns:

(boolean) true

### get_callbacks ()

Get authentication callbacks.

Returns:

(table) callbacks

## Configuration

### set_params (opts)

Modify authentication params. (Changed in v0.11)

Can’t be used before the bootstrap. Affects all cluster instances. Triggers `cluster.config_patch_clusterwide` .

Parameters:

- opts:

  - enabled: (optional boolean) (Added in v0.11)

  - cookie_max_age: (optional number)

  - cookie_renew_age: (optional number) (Added in v0.11)

Returns:

(boolean) true

Or

(nil)

(table) Error description

### get_params ()

Retrieve authentication params.

Returns:

(AuthParams)

### AuthParams

Authentication params.

Fields:

- enabled: (boolean) Wether unauthenticated access is forbidden

- cookie_max_age: (number) Number of seconds until the authentication cookie expires

- cookie_renew_age: (number) Update provided cookie if it’s older then this age (in seconds)

## Authorizarion

### set_lsid_cookie (user)

Create session for current user.

Creates session for user with specified username and user version or clear it if no arguments passed.

(Added in v2.2.0-43)

Parameters:

- user: (table)

### get_session_username ()

Get username for the current HTTP session.

(Added in v1.1.0-4)

Returns:

(string or nil)

### authorize_request (request)

Authorize an HTTP request.

Get username from cookies or basic HTTP authentication.

(Added in v1.1.0-4)

Parameters:

- request: (table)

Returns:

(boolean) Access granted

### render_response (response)

Render HTTP response.

Inject set-cookie headers into response in order to renew or reset the cookie.

(Added in v1.1.0-4)

Parameters:

- response: (table)

Returns:

(table) The same response with cookies injected

## User management

### UserInfo

User information.

Fields:

- username: (string)

- fullname: (optional string)

- email: (optional string)

- version: (optional number)

### add_user (username, password, fullname, email)

Trigger registered add_user callback.

The callback is triggered with the same arguments and must return a table with fields conforming to `UserInfo` . Unknown fields are ignored.

Parameters:

- username: (string)

- password: (string)

- fullname: (optional string)

- email: (optional string)

Returns:

(UserInfo)

Or

(nil)

(table) Error description

### get_user (username)

Trigger registered get_user callback.

The callback is triggered with the same arguments and must return a table with fields conforming to `UserInfo` . Unknown fields are ignored.

Parameters:

- username: (string)

Returns:

(UserInfo)

Or

(nil)

(table) Error description

### edit_user (username, password, fullname, email)

Trigger registered edit_user callback.

The callback is triggered with the same arguments and must return a table with fields conforming to `UserInfo` . Unknown fields are ignored.

Parameters:

- username: (string)

- password: (optional string)

- fullname: (optional string)

- email: (optional string)

Returns:

(UserInfo)

Or

(nil)

(table) Error description

### list_users ()

Trigger registered list_users callback.

The callback is triggered without any arguments. It must return an array of `UserInfo` objects.

Returns:

({UserInfo,…})

Or

(nil)

(table) Error description

### remove_user (username)

Trigger registered remove_user callback.

The callback is triggered with the same arguments and must return a table with fields conforming to `UserInfo` , which was removed. Unknown fields are ignored.

Parameters:

- username: (string)

Returns:

(UserInfo)

Or

(nil)

(table) Error description