Guardian SDK のインストール

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

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

npm install auth0-guardian-js

​

ソースファイル

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

​

Guardian の設定

var auth0GuardianJS = require('auth0-guardian-js')({
	// USテナントの場合: https://{name}.guardian.auth0.com
 	// AUテナントの場合: https://{name}.guardian.au.auth0.com
 	// EUテナントの場合: https://{name}.guardian.eu.auth0.com
  // JPテナントの場合: https://{name}.guardian.jp.auth0.com
	serviceUrl: "https://{{ userData.tenant }}.guardian.auth0.com",
	requestToken: "{{ requestToken }}", // またはticket: "{{ ticket }}" - 以下を参照

	issuer: {
		// OTPジェネレーターアプリに表示する発行者名
		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'); // 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
});

​

認証

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

1. トランザクションを開始します。
2. (任意) ユーザーがすでに登録済みかどうかを確認します。認証するには、登録済みである必要があります。
3. 認証をリクエストします (プッシュ通知または SMS) 。OTP の場合、Request は noop です。
4. OTP を検証します (プッシュの場合、.verify は noop です) 。

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

プッシュ通知が拒否された場合は、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 エラーコードリファレンス