Overview
The Ubiqu Free API is a REST API that allows you to implement a highly secure and simple to use authentication service, for free! If you follow this tutorial to the end, you will be successfully signed up as a Ubiqu Free Service Provider (SP), and you will be able to provide your customers with the best and most secure authentication experience in the world. This tutorial _only_ concerns how to create a Service Provider, please look at our General Ubiqu Free use tutorial for how to use it, and to our exhaustive technical documentation for any further questions you might have.
Signing up as an SP takes a few minutes. This process is fully automated in all plugins (TODO: link to plugin page) we offer and we highly recommend using our official plugins where available, but if you want to roll your own service provider for a custom system that needs secure authentication, or for a framework/platform we have not yet covered, please read on!
If you have the Ubiqu Authenticate app installed on your phone, and a Ubiqu Free asset installed in the app, the sign-up procedure can be explained in 2 simple steps. (plus one optional step for those who would like to customize their Service Provider even further)
1. Create the Service Provider
2. Enter the admin nonce
3. [Optional] Validate your domain
See the flow chart below for a step by step overview, and read on to understand what each step means.
Installing the app and asset
Installing the app is as simple as going to either the play store, or the app store (link)
Installing the asset is as simple as opening the Ubiqu Authenticate app, and following the tutorial for the first time. At the end of this process, a Ubiqu Free Asset will be created for you and you will be required to enter a PIN code twice. PLEASE MAKE SURE TO REMEMBER OR STORE THIS PIN SECURELY. You can reinstall our app as many times as you want, and recreate the Ubiqu Free Asset as many times as you want, but all Service Providers that have been created on the previous Free Asset you had will no longer be accessible.
Create the Service Provider
Creating the service provider is a simple POST request to the end point /api/serviceprovider. We provide examples of this call below.
Request
curl \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name":"Example name","template":"ubiqu","url":"http://example.com","challenge_url":"http://example.com/challenge","callback_url":"http://example.com/callback"}' \
-k https://free.ubiqu-staging.com/api/serviceprovider
Response
{
"result": {
"nonce_formatted": "321 793 428",
"domain_challenge": "VWJRZlJlRV+Bb6A3w+9ODbRjgCUPu/8O7zxHpLYEIsmCprI+PyTU2DYtpDxg0Hr1QVkAyZZxof78Y5FmgoZuhgmkBIb/BfIItsdFFVr3Bw0RBn4cwZIXMQPDhbeyWKEXfMvwx8hDI2F8v9n5XMSYyymAn4wC6DCHL3oPk1xnsV723dodreyF03mJH820xDPX9y4Zu/rxgh9GMkVDNUFFNA==_YskLVd2Uf5fU31Xmn6vMQQ==",
"nonce": "321793428",
"name": "Example name",
"asset_uuid": null,
"api_key": "VWJRZlJlRV+v3CoB3kZAipVeKIPeURis/L8D6R/HCsmpvMCDqvbx6UYyRUM1QUU0_p1jFSiGSVrz2ZaaE/AQ0cg==",
"domain_validated": false,
"uuid": "816fa037c3ef4e0db46380250fbbff0e"
}
}
The response parameter `api_key` contains the API Key that will be needed for subsequent calls. We do not store a copy of it, so make sure to not lose this!
You will see that the `asset_uuid` parameter is null. This will be the free asset that is created for your Service Provider, which is the user account for the Free Asset on your phone for your just created Service Provider.
Enter the admin nonce
Service Providers require an associated admin so that the SP can be managed at a later point in time, and that new API keys can be generated should your current API key be lost. For this reason, a nonce is provided that allows you to link the Ubiqu Free asset in your app to the Service Provider you just created.
Simply open the app, click on the Ubiqu Free asset and enter the nine digit nonce to link.
Note: If this doesn’t happen within 5 minutes, the nonce will be invalidated and the Service Provider will be deleted. No fear! You can re-create as many service providers as you like. However, you can only link your Ubiqu Free Asset to up to 3 Service Providers.
Having entered the nonce successfully, you can do your first GET request to get information about the `asset_uuid` that you can use for further calls. See below for an example /serviceprovide GET request.
Request
curl \ -X GET \ -H "Accept: application/json" \ -H "X-Api-Key: VWJRZlJlRV+v3CoB3kZAipVeKIPeURis/L8D6R/HCsmpvMCDqvbx6UYyRUM1QUU0_p1jFSiGSVrz2ZaaE/AQ0cg==" \ -H "Content-Type: application/json" \ -k https://free.ubiqu-staging.com/api/serviceprovider
Response
{
"result": {
"nonce_formatted": "321 793 428",
"nonce": "321793428",
"name": "Example name",
"asset_uuid": "deadbeefdeadbeefdeadbeefdeadbeef",
"domain_validated": false,
"uuid": "816fa037c3ef4e0db46380250fbbff0e"
}
}
Validate your domain
In order to make full use of templates that require the `url` parameters, we first need to validate that the domain you want to show in the Authenticate app upon an asset request is actually under your control. We use a challenge-response mechanism to do the validation. The steps are relatively simple.
1. Do POST request to /api/serviceprovider/validatedomain
2. Ubiqu Free does GET request to URL indicated by `challenge_url` parameter that was sent when creating the Service Provider. This has to on the same domain the domain of your `url` parameter. Also, we don’t do wildcard domain validations.
3. The body of the response to your `challenge_url` should exist solely of the `domain_challenge` contents that were returned in the response to your service provider creation.
4. Ubiqu Free validates the domain challenge response and responds to the initial POST request with success = true or false. If success is false, we provide a short reason for why the validation failed, to help you debug any problems.
The call that one needs to do kickstart the process.
Request
curl \ -X POST \ -H "X-Api-Key: VWJRZlJlRV+v3CoB3kZAipVeKIPeURis/L8D6R/HCsmpvMCDqvbx6UYyRUM1QUU0_p1jFSiGSVrz2ZaaE/AQ0cg==" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -k https://free.ubiqu-staging.com/api/serviceprovider/validatedomain
Conclusion
We thank you for your interest in our Authentication products and in Ubiqu Free. If you have followed this tutorial to the end you should now be able to continue with our tutorial on how to use our product to really secure your authentication process. You can find the tutorial here –
Alternatively, we suggest looking at our technical documentation, to better understand each individual request and response parameter, so that you can best suit them to your needs.
If you have any questions, or if you’ve found any errors, please drop us an email at boris@ubiqu.com