API v2: User authentication methods management¶

`UserAuthenticationMethodModel`¶
Parameter	Type	Required	Description
id	string	yes	Read-only object Identifier
type	string {certificate, duo, extauth, oath, password, sms, sshkey}	yes	Immutable
user_id	string	yes	Immutable. Expects unique `position`
position	number	yes	Expects unique `user_id`
external_sync	boolean; default value `false`	yes
secret	string	if `type` == `duo` \|\| `oath` \|\| `password` \|\| `sms` \|\| `sshkey` \|\| `token`
needs_change	boolean; default value `false`	yes
external_authentication_id	string	if `type` == `duo` \|\| `extauth` \|\| `oath` \|\| `sms`
certificate_subject	string	if `type` == `certificate`
duo_user_id	string	if `type` == `duo`
duo_username	string	if `type` == `duo`

`OATHAuthenticationMethodModel`¶
Parameter	Type	Required	Description
oath_type	string {HOTP, TOTP}	yes	Immutable
oath_initialized	boolean; default value `false`	yes
oath_secret	string	yes	Protected
oath_tokenlen	number	yes	Immutable; value range: [4, 16]
oath_timestep	number {30, 45, 60, 90, 120, 180, 300}	If `oath_type` == `TOTP`
oath_counter	number; default value `0`	yes	Read-only
oath_timeshift	number; default value `0`	If `oath_type` == `TOTP`	Read-only
oath_url	null		Read-only
oath_qrcode	null		Read-only

Request for retrieving available attributes of the UserAuthenticationMethodModel

Method	GET
Path	/api/v2/objspec/user_authentication_method

Allowed methods

`GET`	for reading data of an existing object; no request body is required
`POST`	for creating an object; requires a request body, specified in JSON format, that contains the values for properties of the object that is about to be created
`PATCH`	for modifying an existing object; requires a request body, specified in JSON format, that contains the values for properties of the object
`DELETE`	for removing an existing object; no request body is required

There is a list of URL parameters available for a specific method to be included within a path:

fields - for including the object fields in the query,

filter - narrows out the result with available additions:

in - include possible field values (separated with comma),

match - include a sequence of characters to be searched in field values,

eq - equal,

ne - not equal,

lt - less than,

le - less or equal,

gt - greater than,

ge - greater than or equal

blocked - filter blocked objects,

!blocked - filter unblocked objects,

isempty() - filter objects with empty values in specified fields, only applies to arrays (e.g., server.isnull()),

order,

offset,

limit,

debug - for showing statistics, database errors, etc,

total_count,

reveal - to see objects: active, removed, or all for both removed and un-removed.

An example of the request that shows a list of 10 users that have a role user with their id and name specified, sorted alphabetically by their names and shows a total count of users that match the given criteria: GET https://<fudo_address>/api/v2/user?fields=id,name&filter=role.eq(user)&order=name&limit=10&total_count

Possible responses

Code	Status
`200`	success	`OK`
`201`	success	`CREATED`
`400`	failure	`BAD REQUEST`; message examples: `Unrecognized endpoint`, `Request body is not allowed for this endpoint`
`401`	failure	`UNAUTHORIZED`
`404`	failure	`BAD REQUEST`; message example: `Object not found`

The next chapter describes procedures for creating separate requests.

Refer to the Batch operations topic to create nested requests for operating on the User objects.

Listing user’s authentication methods¶

Request

Method	GET
Path	/api/v2/user/<user_id>/authentication

Example request

Sending GET https://10.0.0.0/api/v2/user/12345678901234567890/authentication

Response

    {
"result": "success",
"user_authentication_method": [
    {
        "id": "12345612345123",
        "user_id": "12345678901234567890",
        "type": "password",
        "needs_change": false,
        "position": 0,
        "external_sync": false,
        "created_at": "2022-10-25 06:35:12.95741-07",
        "modified_at": "2022-10-25 06:35:12.95741-07",
        "user_name": "test-user"
    },
    {
        "id": "1234561234512357466",
        "user_id": "12345678901234567890",
        "type": "sshkey",
        "needs_change": false,
        "position": 1,
        "external_sync": false,
        "sshkey_user_presence_required": true,
        "sshkey_verification_required": false,
        "sshkey_counter": 0,
        "created_at": "2022-10-25 06:37:54.913056-07",
        "modified_at": "2022-10-25 06:37:54.913056-07",
        "user_name": "test-user"
    }]}

Creating user authentication method¶

Request

Method	POST
Path	/api/v2/user/<user_id>/authentication
Headers	Content-Type: Application/JSON
Body	UserAuthenticationMethodModel

Example request: Setting user authentication method - static password

Sending POST https://10.0.0.0/api/v2/user/12345678901234567890/authentication

{
"type": "password",
"secret": "test-password",
"position":0
 }

Response

    {
"result": "success",
"user_authentication_method": {
    "id": "12345612345123"
}}

Modifying user authentication method¶

Request

Method	PATCH
Path	/api/v2/user/<user_id>/authentication/<id>
Headers	Content-Type: Application/JSON
Body	UserAuthenticationMethodModel

Example request

Request

Sending PATCH https://10.0.0.0/api/v2/user/12345678901234567890/authentication/12345612345123

{
"position":1}

Response

    {
"result": "success"}

Deleting user authentication method¶

Request

Method	DELETE
Path	/api/v2/user/<user_id>/authentication/<id>

Example request

Sending DELETE https://10.0.0.0/api/v2/user/12345678901234567890/authentication/1234561234512357466

Response

    {
"result": "success"}