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, mobiletoken}	yes	Immutable
user_id	string	yes	Immutable. Uniqueness is required in the combination of attribute user_id with attribute position.
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 || mobiletoken || oath || password || sms || sshkey
needs_change	boolean; default value false	yes
external_authentication_id	string	if type == duo || extauth || oath || sms
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
mobiletoken_device_id	string	if type == mobiletoken	Read-only; Expensive to use
mobiletoken_device_platform	string	if type == mobiletoken	Read-only; Expensive to use
mobiletoken_device_pushid	string	if type == mobiletoken	Read-only; Expensive to use
sms_token	string	if type == sms	Read-only; Protected
sshkey_user_presence_required	boolean; default value true	if type == sshkey
sshkey_verification_required	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.

Request for retrieving available attributes of the UserAuthenticationMethodModel

Method	GET
Path	/api/v2/objspec/user_authentication_method

Note

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

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"
}

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:

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

{
    "type": "apikey"
}

Response:

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

Request:

Sending POST https://10.0.0.0/api/v2/user/12345678901234567891/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.

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"
}