on Mar 9, 2020Use 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:
-
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 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": "RSA SecurID Access"
},
"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
}]
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. |