Installer la trousse SDK Guardian

Décrit comment installer, configurer les options et utiliser la trousse SDK Guardian.

La trousse SDK Guardian fournit un client sans interface utilisateur pour Guardian.

npm install auth0-guardian-js

​

Fichiers sources

• Version complète de la trousse SDK
• Version simplifiée de la trousse SDK
• API Guardian complète

​

Configurer 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 }}"
});

L’utilisation d’un requestToken ou d’un ticket dépend de la méthode d’authentification. Le ticket correspond à un ticket d’inscriptiongénéré précédemment.

​

Utiliser un domaine personnalisé

Si vous avez configuré un domaine personnalisé pour votre locataire Auth0, vous devrez mettre à jour la propriété serviceUrl pour qu’elle pointe vers le point de terminaison Guardian.

var auth0GuardianJS = require('auth0-guardian-js')({
    // For custom domains
    serviceUrl: "https://{yourCustomDomain}/guardian/",
    ...
});

​

Inscrire des appareils

L’inscription d’appareils comprend les étapes suivantes :

1. Démarrer la transaction.
2. (facultatif) Vérifier si l’utilisateur est déjà inscrit. Vous ne pouvez pas vous inscrire deux fois.
3. Envoyer les informations nécessaires à l’inscription.
4. Confirmer l’inscription.
5. Montrer le code de récupération.

Certaines étapes peuvent être omises, dépendant de la méthode. Nous fournissons la même interface pour toutes les méthodes afin que vous puissiez écrire un code uniforme. Certaines méthodes complètent l’authentification, tandis que d’autres nécessitent une étape d’authentification supplémentaire. Vous pouvez le déterminer en écoutant l’événement enrollment-complete.

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
});

​

Authentifier

Pour s’authentifier à l’aide d’une méthode, il faut exécuter les étapes suivantes :

1. Démarrer la transaction.
2. (facultatif) Vérifier si l’utilisateur est déjà inscrit. Vous devez être inscrit pour vous authentifier.
3. Demander l’authentification (notification poussée ou SMS). La demande est un noop pour OTP.
4. Vérifier OTP (.verify est un noop pour le Push).

Certaines étapes peuvent être omises en fonction de la méthode; nous fournissons la même interface pour toutes les méthodes afin que vous puissiez écrire un code uniforme. Une fois le facteur vérifié ou le Push accepté, vous recevrez un événement auth-response avec la charge utile à envoyer au serveur; vous pouvez utiliser auth0GuardianJS.formPostHelper(’{{ postActionURL }}’, payload) pour renvoyer le message au serveur.

Vous pouvez également recevoir auth-rejected si la notification poussée a été reçue.

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);
		});
	});
}

​

En savoir plus

• Référence du code d’erreur Guardian