Cloud Administration FIDO Authenticator APICloud 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 AdminRequired Information from the Super Admin
The Super Admin must provide you with the following information:
-
The relying part (RP_ID) to use for FIDO authentication. This value must be configured in the Cloud Administration Console. See Allow FIDO Authentication to a Third-Party Domain.
-
A file containing the Administration API key to use with this API. This key generates the JSON Web Token for an API request. The key must be associated with the Super Admin role. To generate a key, see Authentication for the Cloud Administration APIs.
Software Developer KitSoftware Developer Kit
You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.
Register a FIDO AuthenticatorRegister a FIDO Authenticator
The following sections demonstrate how to register a FIDO authenticator.
Attestation Options Request URL 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 ParametersAttestation 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 BodyExample 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 BodyExample 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 URLAttestation 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 ParametersAttestation 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 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 Example Attestation Result Response
{
"authenticatorName": "user's Security key 1",
"authenticatorId":
"W2DlRdl77VCvFQD7seK_GnNxV005QDmm_6IJpAIimrYPQnENDJQ46Fv5Dar9TzyeT_T7JPPwJjXNaAaerWS-9Q",
"serverResponse": {
"status": "ok",
"errorMessage": ""
}
}
Authenticate a FIDO User Authenticate a FIDO User
FIDO Authentication Assertion Options Request URLFIDO 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 ParametersFIDO 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 RequestExample Assertion Options Request
{
rpId: String,
serverPublicKeyCredentialGetOptionsRequest : {
username: String,
userVerification: String,
extensions: {
key: Object,
key: Object
}
}
}
Example Assertion Options ResponseExample 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 URLFIDO 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 ParametersFIDO 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 ResultExample FIDO Authentication Assertion Result
{
serverPublicKeyCredential : {
id: String,
rawId: String,
type: String,
response: {
clientDataJSON: String,
authenticatorData: String,
signature: String,
userHandle: String
}
}
}
Example FIDO Authentication Assertion ResponseExample 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 AuthenticatorsList, 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 ResponseList 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 RequestUpdate FIDO Authenticators Example Request
{
name: String
}
Update FIDO Authenticators Example ResponseUpdate 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 ResponseDelete 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 CodesResponse 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. |
