Introduction
Welcome r to the Regzen documentation. This guide will help you easily integrate Sign in with Regzen to your website.
Setup
Step 1: Including the Library
Include the Regzen JavaScript Library libary as an NPM module or as a script tag.
If included as a script tag, a RegzenClient
global object will be exposed:
Include
<!-- Include the regzen-client script using a script tag. -->
<script src="https://unpkg.com/regzen-client/dist/regzen.min.js"></script>
# Or install regzen-client as a node module.
$ npm install regzen-client --save
// And later, use it like this:
import RegzenClient from "regzen-client";
Step 2: Instantiating the Client
Instantiate the client with the application id we have provided you.
Instantiate
const regzen = new RegzenClient({
applicationId: "YOUR_APPLICATION_ID",
});
Step 3: Starting the Sign In Process
You should add the "Sign in with Regzen" button and start the sign in process by calling the regzen.signIn
method.
Usage
<div class="regzen-sign-in" onclick="regzen.signIn()"></div>
Step 4: Handling the Authorization Code
After the user has scanned the QR code and approved the authorization request using the Regzen mobile app, an authorization code will be generated. The Regzen JavaScript Library library will retrieve this authorization code and hand it to you using the regzen.onGranted
event. You need to pass this authorization code to your backend and exchange it with the Regzen API in order to retrieve the user's data.
Note: This authorization code can be used only once and also expires after a short time. If it expires, you'll need to start over and get a new one.
We have libraries for various technologies which can handle the exchange communication for you:
Support for more languages is coming soon.
If there is currently no library for your language, see the Exchange Authorization Code section for information on how to do this manually.
Handle Authorization Code
regzen.onGranted(function (authorizationCode) {
// Send the authorization code to the Regzen API.
});
Step 5: Showing the "Protected by Regzen" Alert
When one of your users chooses to sign in to your website using Regzen, you shouldn't allow them to use their password to sign in anymore. You can do this by keeping additional information about every user in your database, something like is_using_regzen
and setting that to true
if the user used Regzen to sign in. Regzen provides you with a convenient regzen.showProtectedAlert
method to show an alert and notify your users that they should use Regzen to sign in instead of a password.
Note: You can override the styles of this alert by following the SweetAlert theming guide.
Showing Alert
function logIn() {
// Call an endpoint on your API to check if user is using Regzen.
const response = await fetch('https://api.yourapp.com/[email protected]');
const user = response.json();
if (user.is_using_regzen) {
// Show the "Protected by Regzen" alert.
regzen.showProtectedAlert();
} else {
// Call additional endpoint to log in user if he is not using Regzen.
}
}
Step 6: Handling Sign in with Regzen Removal
Using the mobile app, users can choose to no longer use Regzen to sign in to your website and revert back to using their password. Regzen will notify you of this by sending an HTTP POST
request with some encrypted payload (see notes below) to your webhook URL. You can set this URL when registering your application. It is up to you to choose if you will revert your users to their old password or send them an email for resetting their password.
Note 1: The request body data is encrypted and you will have to follow the steps in the Decrypting the Response section to extract the raw data. After successful decryption, you will get a stringified JSON with the data (see on the right).
Note 2: If you're using any of Regzen libraries which can handle the exchange communication for you, you're also supplied with payload decryption function. Please refer to the official documentation of corresponding Regzen library.
Decrypted Request Body
{
"email": "[email protected]" // Email of the user who chose to no longer use Regzen.
}
Step 7: Handling Other Events
You can provide event handlers for the following events:
Event | Parameters | Description |
---|---|---|
onDenied | Called when the user denies the authorization request. | |
onTimedOut | Called when the authorization request times out. | |
onError | error | Called when an unexpected error occurs from Regzen's side. |
Event Handling
regzen.onDenied(function () {
// Give some feedback to the user when the authorization request was denied.
});
regzen.onTimedOut(function () {
// Give some feedback to the user when the authorization request timed out.
});
regzen.onError(function (error) {
// Give some feedback to the user when an unexpected error occured..
});
Regzen API Endpoints
Exchange Authorization Code
Exchange authorization code generated by the Regzen API for user data.
Note: The user data is encrypted and you will have to follow the steps in the Decrypting the Response section to extract the raw data.
$ curl "https://api.regzen.com/api/oauth/exchange?authorization_code=497c4bb7f892f0b03d8a9f7c6ead70bc"
HTTP Request
GET https://api.regzen.com/api/oauth/exchange
Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
authorization_code | Yes | string | ex. 497c4bb7f892f0b03d8a9f7c6ead70bc |
Response
Response
{
"data": "ENCRYPTED_USER_DATA"
}
Status code | Description |
---|---|
200 | The authorization code was exchanged for user data and the operation was successful. |
403 | The provided authorization code is invalid or expired. |
422 | The format of the provided authorization code is invalid. |
500 | Something went wrong while processing the request. |
Decrypting the Response
Step 1: Decode the data from Base64. After decoding, your data will be in this format:
[INITIALIZATION_VECTOR][ENCRYPTED_MESSAGE_HASH][ENCRYPTED_MESSAGE]
Note: Brackets are not part of the data, they are just used to illustrate the structure of the data.
Step 2: Extract the first 16 characters for the initialization vector.
Step 3: The next 32 characters represent the hash generated by HMAC SHA-256
. Generate your own hash using the same algorithm by hashing [ENCRYPTED_MESSAGE]
with your application secret as the key. The hashes need to match in order to confirm the integrity of the message.
Step 4: Use something like openssl_decrypt to decrypt the [ENCRYPTED_MESSAGE]
with AES-256-CBC
using your application secret as the key and the data extracted in step 2 as the initialization vector.
Step 5: After successful decryption, you will get a stringified JSON with the user data.
JSON Structure
{
"email": "[email protected]"
}