Guardian SDK をインストールする

Guardian SDK のインストール方法、オプションの設定、および使用方法について説明します。

Guardian SDK は、Guardian 向けの UI を備えないクライアントを提供します。

npm install auth0-guardian-js

​

ソースファイル

• 完全版 SDK
• 圧縮版 SDK
• Guardian API の全体

​

Guardian の設定

var auth0GuardianJS = require('auth0-guardian-js')({
	// 米国テナントの場合: https://{name}.guardian.auth0.com
 	// オーストラリアテナントの場合: https://{name}.guardian.au.auth0.com
 	// EUテナントの場合: https://{name}.guardian.eu.auth0.com
  // 日本テナントの場合: https://{name}.guardian.jp.auth0.com
	serviceUrl: "https://{{ userData.tenant }}.guardian.auth0.com",
	requestToken: "{{ requestToken }}", // または ticket: "{{ ticket }}" - 以下を参照

	issuer: {
		// OTPジェネレーターアプリに表示するIssuer名
		label: "{{ userData.tenantFriendlyName }}",
		name: "{{ userData.tenant }}",
	},

	// OTPジェネレーターアプリに表示するアカウントラベル
	accountLabel: "{{ userData.friendlyUserId }}",

	// 任意。デバッグ目的のみ。
	// 複数のリクエストを同一の「トランザクション」（広義）として
	// 関連付けるためのID
	globalTrackingId: "{{ globalTrackingId }}"
});

requestToken と ticket のどちらを使用するかは、認証方法によって異なります。ticket は、事前に生成された登録チケットに対応します。

​

カスタムドメインを使用する

Auth0 のテナントにカスタムドメインが設定されている場合は、serviceUrl プロパティを更新して Guardian エンドポイントを参照するようにする必要があります。

var auth0GuardianJS = require('auth0-guardian-js')({
    // カスタムドメインの場合
    serviceUrl: "https://{yourCustomDomain}/guardian/",
    ...
});

​

デバイスを登録する

デバイスの登録は、次の手順で行います。

1. トランザクションを開始します。
2. (任意) ユーザーがすでに登録済みかどうかを確認します。重複して登録することはできません。
3. 登録に必要な情報を送信します。
4. 登録を確認します。
5. リカバリーコードを表示します。

方式によっては、一部の手順を省略できます。すべての方式で同じインターフェースを提供しているため、統一的なコードを記述できます。認証まで完了する方式もあれば、追加の認証手順が必要な方式もあります。これは、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'); // 電話番号を取得する
	}

	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'); // 検証用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) // SMSの場合
});

​

認証

ある方式で認証するには、次の手順を実行する必要があります。

1. トランザクションを開始します。
2. (任意) ユーザーがすでに登録済みかどうかを確認します。認証するには、事前に登録されている必要があります。
3. 認証要求 (プッシュ通知または SMS) を送信します。OTP の場合、この要求は no-op です。
4. OTP を検証します (プッシュの場合、.verify は no-op です) 。

方式によっては省略できる手順もありますが、どの方式でも同じインターフェースを提供しているため、共通のコードを記述できます。認証要素の検証が完了するか、プッシュが承認されると、サーバーに送信するペイロードを含む auth-response イベントを受信します。auth0GuardianJS.formPostHelper('{{ postActionURL }}', payload) を使用して、そのメッセージをサーバーに POST で返送できます。

プッシュ通知が届いた場合は、auth-rejected を受信することもあります。

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

​

詳細情報

• Guardian エラーコードリファレンス