Install Guardian SDK
The Guardian SDK provides a UI-less client for Guardian.
npm install auth0-guardian-js
Source files
Configure Guardian
var auth0GuardianJS = require('auth0-guardian-js')({
// For US tenants: https://{name}.guardian.auth0.com
// For AU tenants: https://{name}.guardian.au.auth0.com
// For EU tenants: https://{name}.guardian.eu.auth0.com
// For JP tenants: https://{name}.guardian.jp.auth0.com
serviceUrl: "https://{{ userData.tenant }}.guardian.auth0.com",
requestToken: "{{ requestToken }}", // or ticket: "{{ ticket }}" - see below
issuer: {
// The issuer name to show in OTP Generator apps
label: "{{ userData.tenantFriendlyName }}",
name: "{{ userData.tenant }}",
},
// The account label to show in OTP Generator apps
accountLabel: "{{ userData.friendlyUserId }}",
// Optional, for debugging purpose only,
// ID that allows to associate a group of requests
// together as belonging to the same "transaction" (in a wide sense)
globalTrackingId: "{{ globalTrackingId }}"
});
Was this helpful?
Use of requestToken
or ticket
depends on the authentication method. Ticket corresponds to a previously generated enrollment ticket.
Use a custom domain
If you have a custom domain configured for your Auth0 tenant, you'll need to update the serviceUrl
property to point to the Guardian endpoint:
var auth0GuardianJS = require('auth0-guardian-js')({
// For custom domains
serviceUrl: "https://{yourCustomDomain}/guardian/",
...
});
Was this helpful?
Enroll devices
Enrolling devices consists of the following steps:
Start the transaction.
(optional) Check if the user is already enrolled. You cannot enroll twice.
Send the information needed to enroll.
Confirm enrollment.
Show the recovery code.
Some steps can be omitted depending on the method. We provide the same interface for all methods so you can write uniform code. Some of the methods complete the authentication, whereas others need an extra authentication step. You can determine that by listening to the enrollment-complete
event.
function enroll(transaction, method) {
if (transaction.isEnrolled()) {
console.log('You are already enrolled');
return;
}
var enrollData = {};
if (method === 'sms') {
enrollData.phoneNumber = prompt('Phone number'); // Collect phone number
}
return transaction.enroll(method, enrollData, function (err, otpEnrollment) {
if (err) {
console.error(err);
return;
}
var uri = otpEnrollment.getUri();
if (uri) {
showQR(uri);
}
var confirmData = {};
if (method === 'otp' || method === 'sms') {
confirmData.otpCode = prompt('Otp code'); // Collect verification otp
}
otpEnrollment.confirm(confirmData);
});
}
auth0GuardianJS.start(function(err, transaction) {
if (err) {
console.error(err);
return;
}
transaction.on('error', function(error) {
console.error(error);
});
transaction.on('timeout', function() {
console.log('Timeout');
});
transaction.on('enrollment-complete', function(payload) {
if (payload.recoveryCode) {
alert('Recovery code is ' + payload.recoveryCode);
}
if (payload.authRequired) {
showAuthenticationFor(transaction, payload.enrollment);
return;
}
});
transaction.on('auth-response', function(payload) {
if (payload.recoveryCode) {
alert('The new recovery code is ' + payload.recoveryCode);
}
if (!payload.accepted) {
alert('Authentication has been rejected');
return;
}
auth0GuardianJS.formPostHelper('{{ postActionURL }}', { signature: payload.signature });
});
var availableEnrollmentMethods = transaction.getAvailableEnrollmentMethods();
method = prompt('What method do you want to use, select one of '
+ availableEnrollmentMethods.join(', '));
enroll(transaction, method) // For sms
});
Was this helpful?
Authenticate
To authenticate with a method you need to execute the following steps:
Start the transaction.
(optional) Check if the user is already enrolled. You need to be enrolled to authenticate.
Request the auth (the push notification or SMS). Request is a noop for OTP.
Verify the OTP (
.verify
is a noop for push).
Some steps can be omitted depending on the method, we provide the same interface for all methods so you can write uniform code. After the factor is verified or the push accepted you will receive an auth-response
event with the payload to send to the server, you can use the auth0GuardianJS.formPostHelper('{{ postActionURL }}', payload)
to post back the message to the server.
You may also receive auth-rejected
if the push notification was received.
function authenticate(method) {
auth0GuardianJS.start(function (err, transaction) {
if (err) {
console.error(err);
return;
}
if (!transaction.isEnrolled()) {
console.log('You are not enrolled');
return;
}
transaction.on('error', function(error) {
console.error(error);
});
transaction.on('timeout', function() {
console.log('Timeout');
});
transaction.on('auth-response', function(payload) {
if (payload.recoveryCode) {
alert('The new recovery code is ' + payload.recoveryCode);
}
if (!payload.accepted) {
alert('Authentication has been rejected');
return;
}
auth0GuardianJS.formPostHelper('{{ postActionURL }}', { signature: payload.signature });
});
var enrollment = transaction.getEnrollments()[0];
if (enrollment.getAvailableAuthenticatorTypes().length === 0) {
alert('Somethings went wrong, seems that there is no authenticators');
return;
}
transaction.requestAuth(enrollment, { method: method } function(err, auth) {
if (err) {
console.error(err);
return;
}
var data = {};
if (method === 'sms' || method === 'otp') {
data.otpCode = prompt('Otp code');
} else if (method === 'recovery-code') {
data.recoveryCode = prompt('Recovery code');
}
return auth.verify(data);
});
});
}
Was this helpful?