API v2: User Authentication Methods Management

UserAuthenticationMethodModel

Attribute	Type	Required	Description
id	string	yes	Read-only object Identifier
type	string {password, oath, extauth, sshkey, certificate, duo, sms, apikey}	yes	Immutable
user_id	string	yes	Immutable. Uniqueness is required in the combination of attribute user_id with attribute position. Requires read right on object type user for GET requests, and modify right for DELETE, PATCH, and POST requests.
user_name	string		Read-only; Expensive to use
position	number	yes	Uniqueness is required in the combination of attribute position with attribute user_id.
external_sync	boolean; default value false	yes
secret	string	if type == duo || oath || password || sms || sshkey
needs_change	boolean; default value false	yes
external_authenti- cation_id	string	if type == duo || extauth || oath || sms
apikey_device_id	string	if type == apikey	Read-only; Expensive to use
apikey_device_platform	string	if type == apikey	Read-only; Expensive to use
apikey_device_pushid	string	if type == apikey	Read-only; Expensive to use
apikey_key	string	if type == apikey	Protected
certificate_subject	string	if type == certificate
duo_user_id	string	if type == duo
duo_username	string	if type == duo
OATH	OATHAuthentication- MethodAttributes	if type == oath	OATH authentication method properties
sms_token	string	if type == sms	Read-only; Protected
sshkey_user_presen- ce_required	boolean; default value true	if type == sshkey
sshkey_verification_re- quired	boolean; default value false	if type == sshkey
sshkey_counter	number	if type == sshkey	Read-only
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only

OATHAuthenticationMethodAttributes

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

Retrieve Available Attributes of the UserAuthentication - MethodModel

Request

Method	GET
Path	/api/v2/objspec/user_authentication_method

To check allowed methods, available URL parameters and possible responses please refer to the API Overview section.

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

Listing User Authentication Configurations

Request

Method	GET
Path	/api/v2/user/authentication

Example Request

GET /api/v2/user/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"
    }
  ]
}

Listing Authentication Configurations for User

Request

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

Example Request

GET /api/v2/user/<id>/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"
    }
  ]
}

Retrieve User Authentication Configuration by ID

Request

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

Example Request

GET /api/v2/user/<id>/authentication/<id>`

Response

{
  "result": "success",
  "user_authentication_method": [
    {
      "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"
    }
  ]
}

Create 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

POST /api/v2/user/<id>/authentication`

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

Response

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

Example Request: Setting User Authentication Method - API Key

Note

When creating API Key authentication method, you can:

• set apikey_key=null or skip this attribute in the request - API will generate an apikey_key and return it in the response.

• set apikey_key=<plaintext> - API will save provided plaintext without returning it in the response.

• set apikey_key=sha512:<hash-base64-encoding> - API will save provided hash. Please be informed that the SHA512 hash should be encoded in Base64 formatting.

Note

You can use following command to generate an apikey_key and its hash. The apikey_key will be saved in the apikey.txt file, and the hash will be saved in the apikey.sha512 file.

(umask 077 && echo sha512:$(openssl rand 48 | openssl base64 | tee apikey.txt | dd bs=64 count=1 | openssl sha512 -binary | openssl base64 -A) > apikey.sha512)

Request:

POST /api/v2/user/<id>/authentication`

{
    "type": "apikey"
}

Response:

{
    "result": "success",
    "user_authentication_method": {
        "id": "8511803295730237450",
        "apikey_key": "Ah08ibgN98TAUsa8f7o3MDsJXnliodphdtSz5xzTsnVI4DLv0dfUn6s3BEubse7O"
    }
}

Request:

POST /api/v2/user/<id>/authentication`

{
    "type": "apikey",
    "position": 1,
    "apikey_key": "sha512:rPXbZAJ5q/4GcHTC7Z0x8a568eVqrXuhzmmPjqHPMGovdbCaczEI7WxLw8oyAzKkUV2qWlr9n9g+70K4p12xKw=="
}

Response:

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

Note

The apikey_key plain text is available only during authentication method creation process. Please remember to copy and archive it if needed.

Modify User Authentication Method

Request

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

Example Request

Request

PATCH /api/v2/user/<id>/authentication/<id>`

{
  "position": 1
}

Response

{
  "result": "success"
}

Deleting User Authentication Method

Request

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

DELETE /api/v2/user/<id>/authentication/<id>`

Response

{
  "result": "success"
}