Cloud Administration FIDO Authenticator API

Use this API to integrate FIDO authenticator management into your own applications and tools. The API can perform the following tasks for a user:

Required Information from the Super Admin

The Super Admin must provide you with the following information:

Software Developer Kit

You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.

Register a FIDO Authenticator

The following sections demonstrate how to register a FIDO authenticator.

Attestation Options Request URL

Use the following information to begin the registration process. The <userId> is a unique user identifier that is returned in the response to the Cloud Administration User Details API.

Method Request URL Response Codes
POST /AdminInterface/restapi/v1/fido/<userId>/attestation/options HTTP/1.1 200, 400, 404, 500

Attestation Request and Response Parameters

Parameter Description
rpId The host name of the host requesting authentication. Use domain name format. For example, abcd.com. This value must be configured in the Cloud Administration Console.
serverPublicKeyCredentialCreationOptionsRequest See FIDO Alliance documentation here.
serverPublicKeyCredentialCreationOptionsResponse See FIDO Alliance documentation here.

Example Attestation Request Body

{

"rpId": "domain.com",

"serverPublicKeyCredentialCreationOptionsRequest": {

"username": "user@somedoamin.com",

"displayName": "user@somedoamin.com",

"authenticatorSelection": {

"authenticatorAttachment": "cross-platform",

"requireResidentKey": false,

"residentKey": "preferred",

"userVerification": "preferred"

},

"attestation": "direct",

"extensions": {}

}

}

Example Attestation Response Body

{

"serverPublicKeyCredentialCreationOptionsResponse": {

"status": "ok",

"errorMessage": "",

"rp": {

"id": "domain.com",

"name": "SecurID"

},

"user": {

"id": "ODczODgzM2QtYzYzNy00YTA0LWI0YzQtMDRlYWQ1YmVkYTJh",

"name": "user@somedoamin.com",

"displayName": "user@somedoamin.com"

},

"challenge": "DNfhCo1EJpfsgPIWoa-wDbb25q1jvzB8JKXPU3rdNgI",

"pubKeyCredParams": [

{

"type": "public-key",

"alg": -257

},

{

"type": "public-key",

"alg": -258

},

{

"type": "public-key",

"alg": -259

},

{

"type": "public-key",

"alg": -7

},

{

"type": "public-key",

"alg": -35

},

{

"type": "public-key",

"alg": -36

}

],

"timeout": 50000,

"excludeCredentials": [],

"authenticatorSelection": {

"authenticatorAttachment": "cross-platform",

"residentKey": "preferred",

"userVerification": "preferred"

},

"attestation": "direct"

}

}

Attestation Result URL

The attestation result uses the following URL. The <userId> is a unique user identifier that is returned in the response to the Cloud Administration User Details API.

Method Result URL Response Codes
POST /AdminInterface/restapi/v1/fido/<userId>/attestation/result HTTP/1.1 200, 400, 404, 500

Attestation Result Request and Response Parameters

Parameter Description
serverPublicKeyCredential See FIDO Alliance documentation here.
authenticatorName The automatically-generated name of the registered authenticator. This name appears on the Cloud Administration Console device management pages, and on My Page if My Page is enabled.
authenticatorId Base64url encoded credential ID of the public key credential.
status Value is OK for successful result, or failed for an unsuccessful result.

Example Attestation Result Request

{

"serverPublicKeyCredential": {

"rawId":

"W2DlRdl77VCvFQD7seK_GnNxV005QDmm_6IJpAIimrYPQnENDJQ46Fv5Dar9TzyeT_T7JPPwJjXNaAaerWS-9Q",

"response": {

"attestationObject":"o2NmbXRmcGFja2VkZ2F0dFN0bXSjY2FsZyZgwRgIhAP8yfOf1m-9XuwBIdh4GscFy3wzze5xORvT8fpBp_aOmAiEA65qegtF1Nzza_70RJKsbMbvjglVD47TRi8-ud058YyhjeDVjgVkCwjCCAr4wggGmoAMCAQICBHSG_cIwDQYJKoZIhvcNAQELBQAwLjEsMCoGA1UEAxMjWXViaWNvIFUyRiBSb290IENBIFNlcmlhbCA0NTcyMDA2MzEwIBcNMTQwODAxMDAwMDAwWhgPMjA1MDA5MDQwMDAwMDBaMG8xCzAJBgNVBAYTAlNFMRIwEAYDVQQKDAlZdWJpY28gQUIxIjAgBgNVBAsMGUF1dGhlbnRpY2F0b3IgQXR0ZXN0YXRpb24xKDAmBgNVBAMMH1l1YmljbyBVMkYgRUUgU2VyaWFsIDE5NTUwMDM4NDIwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASVXfOt9yR9MXXv_ZzE8xpOh4664YEJVmFQ-ziLLl9lJ79XQJqlgaUNCsUvGERcChNUihNTyKTlmnBOUjvATevto2wwajAiBgkrBgEEAYLECgIEFTEuMy42LjEuNC4xLjQxNDgyLjEuMTATBgsrBgEEAYLlHAIBAQQEAwIFIDAhBgsrBgEEAYLlHAEBBAQSBBD4oBHzjApNFYAGFxEfntx9MAwGA1UdEwEB_wQCMAAwDQYJKoZIhvcNAQELBQADggEBADFcSIDmmlJ-OGaJvWn9CqhvSeueToVFQVVvqtALOgCKHdwB-Wx29mg2GpHiMsgQp5xjB0ybbnpG6x212FxESJ-GinZD0ipchi7APwPlhIvjgH16zVX44a4e4hOsc6tLIOP71SaMsHuHgCcdH0vg5d2sc006WJe9TXO6fzV-ogjJnYpNKQLmCXoAXE3JBNwKGBIOCvfQDPyWmiiG5bGxYfPty8Z3pnjX-1MDnM2hhr40ulMxlSNDnX_ZSnDyMGIbk8TOQmjTF02UO8auP8k3wt5D1rROIRU9-FCSX5WQYi68RuDrGMZB8P5-byoJqbKQdxn2LmE1oZAyohPAmLcoPO5oYXV0aERhdGFYxEmWDeWIDoxodDQXD2R2YFuP5K65ooYyx5lc87qDHZdjRQAAAGD4oBHzjApNFYAGFxEfntx9AEBbYOVF2XvtUK8VAPux4r8ac3FXTTlAOab_ogmkAiKatg9CcQ0MlDjoW_kNqv1PPJ5P9Psk8_AmNc1oBp6tZL71pQECAyYgASFYIKS1EwvT8T6IVYnyCxWOrZgNCOHMtYYZMjZVHWwaLe70Ilgg3-DnjfRsn2xGrweY5GtNbInJaPbjrRSrKn7A9Hgl9JA",

"getTransports": {},

"clientDataJSON": "eyJjaGFsbGVuZ2UiOiJETmZoQ28xnNnUElXb2Etd0RiYjI1cTFqdnpCOEpLWFBVM3JkTmdJIiwib3JpZ2luIjoiaHR0cDovL2xvY2FsaG9zdDozMDAwIiwidHlwZSI6IndlYmF1dGhuLmNyZWF0ZSJ9"

},

"getClientExtensionResults": {},

"id":

"W2DlRdl77VCvFQD7seK_GnNxV005QDmm_6IJpAIimrYPQnENDJQ46Fv5Dar9TzyeT_T7JPPwJjXNaAaerWS-9Q",

"type": "public-key"

}

}

Example Attestation Result Response

{

"authenticatorName": "user's Security key 1",

"authenticatorId":

"W2DlRdl77VCvFQD7seK_GnNxV005QDmm_6IJpAIimrYPQnENDJQ46Fv5Dar9TzyeT_T7JPPwJjXNaAaerWS-9Q",

"serverResponse": {

"status": "ok",

"errorMessage": ""

}

}

Authenticate a FIDO User

FIDO Authentication Assertion Options Request URL

Use the following URL to create an assertion to request FIDO authentication.

Method Request URL Response Codes
POST /AdminInterface/restapi/v1/fido/<userId>/assertion/options/ HTTP/1.1 200, 400, 404, 500

FIDO Authentication Assertion Options Request and Response Parameters

Parameter Description
rpId The host name of the host requesting authentication. Use domain name format. For example, abcd.com. This value must be configured in the Cloud Administration Console.
serverPublicKeyCredentialGetOptionsRequest See FIDO Alliance documentation here.
serverPublicKeyCredentialGetOptionsResponse See FIDO Alliance documentation here.

Example Assertion Options Request

{

rpId: String,

serverPublicKeyCredentialGetOptionsRequest : {

username: String,

userVerification: String,

extensions: {

key: Object,

key: Object

}

}

}

Example Assertion Options Response

Success

HTTP /1.1 200 OK

Body:

{

serverPublicKeyCredentialGetOptionsResponse : {

status: String,

errorMessage: String,

challenge: String,

timeout: Integer,

rpId: String,

allowCredentials: [

{

id: String,

type: String,

transports: [

entry: String

]

}

],

userVerification: String,

extensions: {

key: Object,

key: Object

}

}

}

FAIL

HTTP /1.1 400 Bad Request

HTTP /1.1 404 User Not found

HTTP /1.1 500 Internal Server Error

FIDO Authentication Assertion Result URL

Use the following URL for the assertion result.

Method Request URL Response Codes
POST /AdminInterface/restapi/v1/fido/<userId>/assertion/result/ HTTP/1.1 200, 400, 404, 500

FIDO Authentication Assertion Result and Response Parameters

Parameter Description
serverPublicKeyCredential See FIDO Alliance documentation here.
serverResponse Value is OK for successful result, or failed for an unsuccessful result.

Example FIDO Authentication Assertion Result

{

serverPublicKeyCredential : {

id: String,

rawId: String,

type: String,

response: {

clientDataJSON: String,

authenticatorData: String,

signature: String,

userHandle: String

}

}

}

Example FIDO Authentication Assertion Response

Success

HTTP /1.1 200 OK

Body:

{

serverResponse : {

status: String,

errorMessage: String

}

}

FAIL

HTTP /1.1 400 Bad Request

HTTP /1.1 404 User Not found

HTTP /1.1 500 Internal Server Error

List, Update, and Delete FIDO Authenticators

Use the following information to list, update, or delete a FIDO authenticator. If you omit the <authenticatorId>, a list of all authenticators will be returned.

Method Request URL Response Codes

GET

PATCH

DELETE

/AdminInterface/restapi/v1/fido/<userId>/ authenticators/<authenticatorId /HTTP/1.1 200, 400, 404, 500

List FIDO Authenticators Example Response

Success

HTTP /1.1 200 OK

Body:

[{

id: String,

name: String,

aaguid: (optional)

enrollmentDate: EPOCH TIME

status: Enabled

}]

FAIL

HTTP /1.1 400 Bad Request

HTTP /1.1 404 User or Authenticator Not found

HTTP /1.1 500 Internal Server Error

Update FIDO Authenticators Example Request

{

name: String

}

Update FIDO Authenticators Example Response

Success

HTTP /1.1 200 OK

FAIL

HTTP /1.1 400 Bad Request

HTTP /1.1 404 User or Authenticator Not found

HTTP /1.1 500 Internal Server Error

Delete FIDO Authenticators Example Response

Success

HTTP /1.1 200 OK

FAIL

HTTP /1.1 400 Bad Request

HTTP /1.1 404 User or Authenticator Not found

HTTP /1.1 500 Internal Server Error

Response Codes

The API returns the following response codes.

Code Description
200 Request successful.
400 Request unsuccessful.
404 User or authenticator not found.
500 Internal server error.
429 Too many requests.