### 登録
登録とは、第2認証要素とAuth0アカウントとのリンクです。アカウントを登録すると、アイデンティティの確認に必要な第2認証要素の提示が必要になります。まだアプリでプッシュ通知を使用していない場合や、プッシュ通知にあまりなじみがない場合は、詳しくは [Apple Push Notification Service Overview](https://developer.apple.com/go/?id=push-notifications) を参照してください。
登録には、テナントドメインに加えて、次の情報が必要です。
| Variable | Description |
| ------------------ | ------------------------------------------------------------------- |
| **Enrollment URI** | Guardian Web WidgetでスキャンしたQRコード、またはメールやSMSで送信された登録チケットにエンコードされている値。 |
| **APNS Token** | デバイスのApple APNSトークン。64バイトを含む文字列 (16進形式) である必要があります。 |
| **Key Pair** | Auth0 Guardianに対して自身のアイデンティティを証明するために使用するRSA (秘密鍵/公開鍵) のキーペア。 |
情報がそろったら、デバイスを登録できます。
```swift lines theme={null}
Guardian
.enroll(forDomain: "{yourTenantDomain}",
usingUri: "{enrollmentUri}",
notificationToken: "{apnsToken}",
signingKey: signingKey,
verificationKey: verificationKey
)
.start { result in
switch result {
case .success(let enrolledDevice):
// 成功。登録済みデバイスのデータが利用可能です
case .failure(let cause):
// 失敗。causeを確認して原因を調べてください
}
}
```
成功すると、登録情報を取得できます。この情報はアプリケーション内に安全に保存する必要があります。この情報には、登録識別子と、登録情報の更新または削除に使用する、デバイスに関連付けられた Guardian API 用のトークンが含まれます。
#### 署名鍵と検証用キー
Guardian.swift では、署名鍵を生成するための便利なクラスが提供されています。
```swift lines theme={null}
let signingKey = try DataRSAPrivateKey.new()
```
このキーはメモリ内にしか存在しませんが、`Data`形式で取得し、たとえば暗号化されたSQLiteDBに安全に保存できます。
```javascript lines theme={null}
// データを保存する
let data = signingKey.data
// 保存処理を実行する
// Storageから読み込む
let loadedKey = try DataRSAPrivateKey(data: data)
```
ただ、iOS Keychain に保存したいだけなら:
```swift wrap lines theme={null}
let signingKey = try KeychainRSAPrivateKey.new(with: "com.myapp.mytag")
```
上記の例では、キーが作成され、指定したタグの下に自動的に保存されます。取得する場合は、そのタグを使用できます。
```swift wrap lines theme={null}
let signingKey = try KeychainRSAPrivateKey(tag: "com.myapp.mytag")
```
検証用のキーは、たとえば任意の `SigningKey` から取得できます。
```swift lines theme={null}
let verificationKey = try signingKey.verificationKey()
```
### ログインリクエストを許可する
登録が完了すると、ユーザーが MFA で本人確認を行う必要があるたびに、プッシュ通知を受け取ります。Guardian には、APNs から受信したデータを解析し、すぐに使える `Notification` インスタンスを返すメソッドがあります。
```swift lines theme={null}
if let notification = Guardian.notification(from: notificationPayload) {
// Guardianのプッシュ通知を受信しました
}
```
通知インスタンスを取得したら、`allow` メソッドを使って認証リクエストを簡単に許可できます。また、以前に取得した登録済みデバイスの情報もいくつか必要です。登録情報が複数ある場合は、通知と同じ `id` (`enrollmentId` プロパティ) を持つものを見つける必要があります。
情報がそろったら、`device` パラメータには、プロトコル `AuthenticatedDevice` を実装する任意のオブジェクトを指定できます:
```swift lines theme={null}
struct Authenticator: Guardian.AuthenticationDevice {
let signingKey: SigningKey
let localIdentifier: String
}
```
ローカル識別子はデバイスのローカル ID で、登録時にはデフォルトで `UIDevice.current.identifierForVendor` が使われます。あとは次を呼び出すだけです:
```swift lines theme={null}
Guardian
.authentication(forDomain: "{yourTenantDomain}", device: device)
.allow(notification: notification)
.start { result in
switch result {
case .success:
// 認証リクエストが正常に許可されました
case .failure(let cause):
// エラーが発生しました。causeを確認して原因を調べてください
}
}
```
### ログインリクエストを拒否する
認証リクエストを拒否するには、代わりに `reject` を呼び出します。必要に応じて、拒否理由を送信することもできます。拒否理由は Guardian のログに表示されます。
```swift lines theme={null}
Guardian
.authentication(forDomain: "{yourTenantDomain}", device: device)
.reject(notification: notification)
// または reject(notification: notification, withReason: "hacked")
.start { result in
switch result {
case .success:
// 認証リクエストが正常に拒否されました
case .failure(let cause):
// エラーが発生しました。causeを確認して原因を調べてください
}
}
```
### 登録解除
たとえば MFA を無効にする場合など、登録を削除するには、次のリクエストを送信します。
```swift lines theme={null}
Guardian
.api(forDomain: "{yourTenantDomain}")
.device(forEnrollmentId: "{userEnrollmentId}", token: "{enrollmentDeviceToken}")
.delete()
.start { result in
switch result {
case .success:
// 成功、enrollmentが削除されました
case .failure(let cause):
// 失敗しました。causeを確認して原因を調べてください
}
}
```
### モバイル専用のOTP登録を設定する
#### リソースを接続する
Auth0 Dashboard または Guardian SDK を使って、リソースを接続できます。
##### Auth0 Dashboard を使用する
1. Auth0ログインプロンプトにアクセスし、表示されたコード、または別のソースから取得した同様のBase32エンコード済みキーをコピーします。次の手順で、このコードを認証アプリに入力します。
2. コピーしたコードを、Guardian などの認証アプリに追加します。
##### SDKを使用する
1. Guardianライブラリをインポートします。
```swift lines theme={null}
import Guardian
```
2. コードジェネレーターを作成します。
```swift lines theme={null}
let codeGenerator = try Guardian.totp(
base32Secret: enrollmentCode, // ユーザーが入力した登録コード
algorithm: .sha1 // TOTPで使用するアルゴリズム
)
```
3. 生成されたコードを取得します。
```swift lines theme={null}
codeGenerator.code()
```
#### ワンタイムコードを入力
Auth0 のログインプロンプトで、前の手順で生成したワンタイムコードを入力します。
Continueを選択すると、アプリケーションがお使いのユーザーの認証要素として追加されたことを示すメッセージが表示されます。
#### アプリでログインする
認証要素の登録が完了すると、ユーザーはアプリを使ってログインできるようになります。まず、認証方法として Guardian アプリを選択します。
次に、本人確認のため、ログインプロンプトにワンタイムコードを入力します。
