Getting Started
Welcome to our BAO FIDO API.
This API document is designed for those interested in developing FIDO authentication services for their users with BAO FIDO API. Please send us an email for free BETA test beta@baosec.com
This API is still under development and will evolve.
You’ll succeed if you do this.
Here’s some useful information.
Something may not happen if you try and do this.
Something bad will happen if you do this.
Introduction
BAO - Better Authentication Online is a fully FIDO (Fast Identity Online) compliant solution for SMEs. It provides strong and free authentication cloud services that can be easily integrated into SMEs’ existing systems in both server and client sides. In addition, developers do not need to change the existing infrastructure like a database, just call our API and you are ready to go!
In order to use BAO, you need to create an application in our Web Console, then follow the API instruction to complete the integration.
The following example logic flow shows an U2F Registration process by using BAO:
- Call /registerURL API to get a registration URL
- Redirect you web application to this URL
- User plug in an U2F Security Key like a baoKey, and touch it for the confirmation
- Our BAO FIDO server will verify the U2F Security Key, and redirect to the “returnUrl” you provided if succeed, otherwise back to the last page.
- The user now registered a new U2F Security Key
The following example logic flow shows an U2F Authentication process by using BAO:
- Call /signURL API to get an authentication URL
- Redirect you web application to this URL
- User plug in an U2F Security Key like a baoKey, and touch it for the confirmation
- Our BAO FIDO server will verify the U2F Security Key, and redirect to the “returnUrl” you provided if succeed, otherwise back to the last page.
- Call /verify API to verify the “returnUrl” with parameters that redirected to your web application which is important to prevent MitM and phishing attacks
- Let your user login if succeed, otherwise back to the login page.
Implementation Considerations
- You can first try our Console to familiar with the process of our BAO FIDO authentication services by adding an U2F Security Key, like a baoKey or a Yubikey. Our BAO FIDO Server supports all U2F Security Keys on the market.
- During the Registration, since your user has already logged in you web application, the “returnUrl” you can just put something like:
"https://yourwebapplication/profile" - While it’s little bit complicate for the Authentication process, you have to make sure that the “returnUrl” that redirected to your web application was genuine. In this case, you need to have an URL path to consume those parameters like following, Please also refer to the /signURL API.
https://yourwebapplication/u2flogin?username=xxx&returnUrl=xxx&challenge=xxx&signature=xxx - It is important that you web application is fully covered by HTTPS, otherwise you web application is still vulnerable for MitM and phishing attacks.
- DO NOT disclose your API KEY and its SECRET in any cases, and DO NOT use the API KEY to call our API in front-end JavaScript, make all the API calls in back-end.
- Since FIDO standards are new to the web, only few browsers supported including Google Chrome version 38 or later, or Opera version 40 or later. Firefox is also supported however the add-on has to be installed U2F Support Add-on. Make sure that your users knowing this.
- If you have any questions, please do not hesitate to send us an email, we will get back to you in 24 hours.
API endpoint
API endpoint for U2F
https://api.baosec.com/fido/u2f/v1
API endpoint for UAF
https://api.baosec.com/fido/uaf/v1
Authentication
You need to be authenticated for all API requests. You can generate an API key in our BAO console.
Add the API key to all requests as an “Authorization” header.
Nothing will work unless you include this API key
NOTE: There is a space between “fido-auth” and “API_KEY”, for example:
{
"Authorization": "fido-auth 6d4fa5eb-083f-4e1e-a944-37fa7cef1123"
}
"Authorization": "fido-auth API_KEY"
POST Header
Your application will need to add a header in order to send a POST request.
Add “application/x-www-form-urlencoded” to all POST requests as a “Content-Type” header.
Nothing will work unless you include this header with the POST request.
{
"Content-Type": "application/x-www-form-urlencoded"
}
"Content-Type": "application/x-www-form-urlencoded"
Errors
| Code | Name | Description |
|---|---|---|
| 200 | Success | The request was performed successful |
| 400 | Bad Request | We couldn’t process the request |
| 401 | Unauthorized | We couldn’t authenticate the request |
| 404 | Not Found | We couldn’t find the resource |
| 500 | Internal Server Error | A server error occurred |
All error responses will return JSON as the following example formats:
{
"code": 200,
"message": "The URL was valid"
}
or
{
"code": 401,
"message": "Session expired"
}
or
{
"code": 404,
"message": "Return URL not found"
}
/greeting
Greeting with our API for testing your API KEY
Say hallo to our API :-)
{
"code": 200,
"message": "Hello BAO U2F"
}
{
"code": 401,
"message": "API KEY invalid"
}
/registerURL
Generate an U2F register URL
Parameters
- username
- The username that already logged in your application
- returnUrl
- The return URL after successful registered an U2F Security Key
Generate an U2F register URL with the given username and return URL then redirecting to it with your application.
The username must be unique in your application such as an email address.
{
"code": 200,
"message": "https://api.baosec.com/fido/u2f/v1/startRegistration?username=example-user&returnUrl=https://example.com/profile&challenge=d39ea54d7a127294033f6d9ff43e5f3d1f6ded3194bc7cda70acb04d5601872c&signature=fb5dbff9c91d0c7f20b661e076f2a91fdf30512694ffbfef7c5fd056ad569739"
}
{
"code": 400,
"message": "Bad URL format"
}
/signURL
Generate an U2F sign URL
Parameters
- username
- The username that tries to login to your application
- returnUrl
- The return URL after successful authenticated an U2F Security Key
Generate an U2F sign URL with the given username and return URL then redirecting to it with your application.
The username must be unique in your application such as an email address.
The full version of a sign return URL to your application will contain four Query Parameters, “username”, “returnUrl”, “challenge”, and “signature”. For example:
https://example.com/u2flogin?username=xxx&returnUrl=xxx&challenge=xxx&signature=xxx
When doing the request, just add for example “https://example.com/u2flogin” to the “returnUrl” parameter, we will generate the full version for your application. Making sure that you application has such an URL address to consume those parameters in order to verify the sign return URL by calling the API:
POST /verify
{
"code": 200,
"message": "https://api.baosec.com/fido/u2f/v1/startAuthentication?username=example-user&returnUrl=https://example.com/u2fLogin&challenge=d39ea54d7a127294033f6d9ff43e5f3d1f6ded3194bc7cda70acb04d5601872c&signature=fb5dbff9c91d0c7f20b661e076f2a91fdf30512694ffbfef7c5fd056ad569739"
}
{
"code": 400,
"message": "Bad URL format"
}
/verify
Verify the U2F sign return URL
Parameters
- username
- The username that tries to login to your application
- returnUrl
- The return URL after successful authenticated a U2F Security Key
- challenge
- The random challenge that generated in our BAO FIDO server
- signature
- The signature that signed with your API KEY and its SECRET.
After the user successful authenticated with our BAO FIDO server, it will jump back to the return URL that generated with the API:
POST /signURL
Your application should verify the U2F sign return URL with this API that making sure the U2F authentication was genuine.
This also prevent MitM and phishing attacks to your application.
Very important that your application calling this API in order to finish the whole authentication process.
{
"code": 200,
"message": "The URL was valid"
}
{
"code": 401,
"message": "Session expired"
}
{
"code": 401,
"message": "Signature invalid"
}
{
"code": 404,
"message": "Return URL not found"
}
/registered
Check if the user has one or more U2F Security Keys registered.
Parameters
- username
- The username
When login, check if the user has one or more Security Keys registered. If so, your application should jump to our BAO FIDO server page URL by calling the API, in order to authenticate the user with the given username:
POST /signURL
Otherwise, remain the user login with his username and password in your application.
The username must be unique in your application such as an email address.
{
"code": 200,
"message": "User <username@example.com> has registered key(s)"
}
{
"code": 400,
"message": "Unknown username <username>"
}
{
"code": 404,
"message": "User <username@example.com> does not have any registered key"
}
/registrations
Return a list of registered U2F Security Keys.
Parameters
- username
- The username
Return a list of registered U2F Security Keys with the given username. The list will be empty if the user does not have any U2F Security Key registered.
Show the list in your username’s profile so he can choose to deregister a certain U2F Security Key when wanted.
The username must be unique in your application such as an email address.
{
"code": 200,
"message": [
{
"username": "username@example.com",
"version": "U2F_V2",
"enrollmentTime": 1488384211452,
"publicKey": "048875122a3bb2b78289461780fcba0a1b4bc0dbf2c7963597ed06c40ac0e6b2d4a146274efc8f4dd8ae547164ae2e2e8218567d592a75e23b530e8ae9eb993739",
"vendor": "Yubico U2F EE Serial 1432534688"
},
{
"username": "username@example.com",
"version": "U2F_V2",
"enrollmentTime": 1488400884950,
"publicKey": "04916037c8e39ce849d6f52bc865fb20f05512ddc4fd6c31e08932a0704cfa50d6c307f432a61b87e28615ce62a1e5a2d5ab011653aea4c94fa508d52bf8b2bd76",
"vendor": "U2F Security Key--05898144877948084932"
}
]
}
{
"code": 400,
"message": "Unknown username <username>"
}
/deregistration
Deregister the U2F Security Key
Parameters
- username
- The username
- publicKey
- The public key of this U2F Security Key
Deregister the U2F Security Key with the given username and public key.
The user will no longer able to use this U2F Security Key to login again unless re-registering.
The username must be unique in your application such as an email address.
{
"code": 200,
"message": "The U2F Security Key deregistered"
}
{
"code": 404,
"message": "Unknown username or publicKey"
}
/greeting
Greeting with our UAF API for testing your API KEY
Say hallo to our UAF API :-)
{
"code": 200,
"message": "Hello BAO UAF"
}
{
"code": 401,
"message": "API KEY invalid"
}
/regRequest
Return an array of UAF registration requests.
Parameters
- username
- The username
Return an UAF registration requests array with the given username.
Each UAF registration request contains the UAF version that server supports.
The username must be unique in your application such as an email address.
{
"code": 200,
"message": [
{
"header": {
"upv": {
"major": 1,
"minor": 0
},
"op": "Reg",
"appID": "https://api.baosec.com/fido/facets",
"serverData": "VHd2QXpTYTBUMkI5TndpWUVDazlUdjAwRmEyMDVEWTNVbVh5RnpaV0FLay5NVFE1TVRNd016Z3lOVFkxTmcuWVhOay5Ta1JLYUVwRVJYZEtSVEZhVm10M2RscEViRXRqYlZwellUQndRbFpIYkd0V1YwWkhUbFU0",
"exts": null
},
"challenge": "JDJhJDEwJE1ZVkwvZDlKcmZsa0pBVGlkVWFGNU8",
"username": "bao",
"policy": {
"accepted": [
[
{
"aaid": [
"BATS#0001"
],
"vendorID": null,
"keyIDs": null,
"userVerification": 0,
"keyProtection": 0,
"matcherProtection": 0,
"attachmentHint": 0,
"tcDisplay": 0,
"authenticationAlgorithms": null,
"assertionSchemes": null,
"attestationTypes": null,
"authenticatorVersion": 0,
"exts": null
}
],
[
{
"aaid": [
"ABCD#ABCD"
],
"vendorID": null,
"keyIDs": null,
"userVerification": 0,
"keyProtection": 0,
"matcherProtection": 0,
"attachmentHint": 0,
"tcDisplay": 0,
"authenticationAlgorithms": null,
"assertionSchemes": null,
"attestationTypes": null,
"authenticatorVersion": 0,
"exts": null
}
],
[
{
"aaid": [
"EBA0#0001"
],
"vendorID": null,
"keyIDs": null,
"userVerification": 0,
"keyProtection": 0,
"matcherProtection": 0,
"attachmentHint": 0,
"tcDisplay": 0,
"authenticationAlgorithms": null,
"assertionSchemes": null,
"attestationTypes": null,
"authenticatorVersion": 0,
"exts": null
}
]
],
"disallowed": null
}
}
]
}
{
"code": 400,
"message": "Unknown username <username>"
}
/regResponse
Process of UAF registration responses sent from the client.
Parameters
- regResponse
- The array of UAF Registration Responses
Return the Registration records that saved in the server side, only if the status was SUCCESS.
“regResponse” is a serialized JSON array
{
"code": 200,
"message": [
{
"authenticator": {
"AAID": "BATS#0001",
"KeyID": "SkRKaEpERXdKSFE1ZUc1Mlkxb3lkbmRTWjBkc1pHcEZXR2htTTA4",
"deviceId": null,
"username": null,
"status": null
},
"PublicKey": "BLilTYrPovMEzgXEFqYg_f8CAczMRcb9XHK28_-ao9UK818sFqL9HY5a_Z-FdIqIh1F8zxaNF1G6mjhVmUpP70k",
"SignCounter": null,
"AuthenticatorVersion": "0.0",
"tcDisplayPNGCharacteristics": null,
"username": "bao",
"userId": null,
"deviceId": null,
"timeStamp": "1491303825656",
"status": "SUCCESS",
"attestCert": "MIICEjCCAbigAwIBAgIEWOIA0DAKBggqhkjOPQQDAjCBkDELMAkGA1UEBhMCTk8xEDAOBgNVBAgMB09QUExBTkQxDzANBgNVBAcMBkdKT1ZJSzEXMBUGA1UECgwOU2VjbWV0cmljcyBBUy4xDTALBgNVBAsMBEZJRE8xFjAUBgNVBAMMDVNlY21ldHJpY3MgQVMxHjAcBgkqhkiG9w0BCQEWD2ZpZG9AYmFvc2VjLmNvbTAeFw0xNzA0MDMwNzU5MTJaFw0yNzA0MDEwNzU5MTJaMIGQMQswCQYDVQQGEwJOTzEQMA4GA1UECAwHT1BQTEFORDEPMA0GA1UEBwwGR0pPVklLMRcwFQYDVQQKDA5TZWNtZXRyaWNzIEFTLjENMAsGA1UECwwERklETzEWMBQGA1UEAwwNU2VjbWV0cmljcyBBUzEeMBwGCSqGSIb3DQEJARYPZmlkb0BiYW9zZWMuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5NS-0o_TFYZan2_g4fpSN1XPQDEaEWpXUJzOXkKW5YJ0tHtdIGKNVzEzw6T7MeEwrSk4OUE00SBNu74R242-tTAKBggqhkjOPQQDAgNIADBFAiAUNK7w4BKyvLnHp1EnSEFnBxxgcdUVfRDd9qID_7eP4wIhAL1vcosg55wWkm17IY0SGZiz3bJEECEHEHYxwpb66r9u",
"attestDataToSign": "Az64AAsuCQBCQVRTIzAwMDEOLgcAAAABAQAAAQouIABarHj4cCmn03z6n1RxySL_i84TFJaoFw_xnlgent2BegkuJwBKREpoSkRFd0pIUTVlRzUyWTFveWRuZFNaMGRzWkdwRldHaG1NMDgNLggAAAABAAAAAQAMLkEABLilTYrPovMEzgXEFqYg_f8CAczMRcb9XHK28_-ao9UK818sFqL9HY5a_Z-FdIqIh1F8zxaNF1G6mjhVmUpP70k",
"attestSignature": "eQPxzkLRkR2vs3NWKDvng-4WIrzfo6C9WV6bM8OrC-VscV4pPq1l4P4FIq7ke67odXnU2kAa39ZGYreEaDLM4A",
"attestVerifiedStatus": "VALID"
}
]
}
{
"code": 409,
"message": "Authenticator already Registered"
}
/authRequest
Return an array of UAF authentication requests.
Parameters
- trxContent
- OPTIONAL, Transaction Content, must be not empty if present, must less than 200 characters.
- trxType
- OPTIONAL, Transaction Type, must be ‘text/plain’ if present.
Return an UAF authentication requests array.
Each UAF authentication request contains the UAF version that server supports.
A Transaction contains a base64-url encoded transaction content according to the contentType to be shown to the user.
{
"code": 200,
"message": [
{
"header": {
"upv": {
"major": 1,
"minor": 0
},
"op": "Auth",
"appID": "https://api.baosec.com/fido/facets",
"serverData": "NFhoU2l1X1JYX1h3Vm5SbU5ES2JOaF9Qc0I3WXl3a1ZwNHd0a0I1U3F2Yy5NVFE1TVRNd016a3hNelF3TUEuU2tSS2FFcEVSWGRLUjNkNFRqSndXRTFFUmxwVlNIQjBZVmN3TWxWWVpGaFNTRVYyWVZNMA",
"exts": null
},
"challenge": "JDJhJDEwJGwxN2pXMDFZUHptaW02UXdXRHEvaS4",
"transaction": null,
"policy": {
"accepted": [
[
{
"aaid": [
"BATS#0001"
],
"vendorID": null,
"keyIDs": null,
"userVerification": 0,
"keyProtection": 0,
"matcherProtection": 0,
"attachmentHint": 0,
"tcDisplay": 0,
"authenticationAlgorithms": null,
"assertionSchemes": null,
"attestationTypes": null,
"authenticatorVersion": 0,
"exts": null
}
],
[
{
"aaid": [
"ABCD#ABCD"
],
"vendorID": null,
"keyIDs": null,
"userVerification": 0,
"keyProtection": 0,
"matcherProtection": 0,
"attachmentHint": 0,
"tcDisplay": 0,
"authenticationAlgorithms": null,
"assertionSchemes": null,
"attestationTypes": null,
"authenticatorVersion": 0,
"exts": null
}
],
[
{
"aaid": [
"EBA0#0001"
],
"vendorID": null,
"keyIDs": null,
"userVerification": 0,
"keyProtection": 0,
"matcherProtection": 0,
"attachmentHint": 0,
"tcDisplay": 0,
"authenticationAlgorithms": null,
"assertionSchemes": null,
"attestationTypes": null,
"authenticatorVersion": 0,
"exts": null
}
]
],
"disallowed": null
}
}
]
}
{
"code": 400,
"message": "Unknown error"
}
/authResponse
Process of UAF authentication responses sent from the client.
Parameters
- authResponse
- The array of UAF Authentication Responses
Return the Authentication records that verified by server.
“authResponse” is a serialized JSON array
{
"code": 200,
"message": [
{
"AAID": "BATS#0001",
"KeyID": "SkRKaEpERXdKSFE1ZUc1Mlkxb3lkbmRTWjBkc1pHcEZXR2htTTA4",
"deviceId": null,
"username": "bao",
"status": "SUCCESS"
}
]
}
{
"code": 400,
"message": "Unknown error"
}
/deregRequest
De-register UAF authentication(s)
Parameters
- deregRequest
- The array of UAF Deregistration Request
De-register UAF authentication(s) on the server and device.
Each UAF deregistration request contains the UAF version that server supports.
“deregRequest” is a serialized JSON array
{
"code": 200,
"message": "Authentication(s) de-registered"
}
{
"code": 400,
"message": "Failure: problem processing deregistration request"
}