### 登録
登録とは、第2要素と Auth0 アカウントを関連付けることです。アカウントが登録されると、本人確認に必要な第2要素の提示が求められます。アプリでまだプッシュ通知を使用していない場合、またはプッシュ通知に不慣れな場合は、詳細について [Apple Push Notification Service Overview](https://developer.apple.com/go/?id=push-notifications) を参照してください。
登録には、テナントドメインに加えて、次の情報が必要です。
| 変数 | 説明 |
| ------------------ | ------------------------------------------------------------------------ |
| **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
// 保存処理を実行する
// ストレージから読み込む
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:
// 成功、登録が削除されました
case .failure(let cause):
// 失敗しました。causeを確認して原因を調べてください
}
}
```
### モバイル限定の OTP 登録を設定する
#### リソースを接続する
Auth0 Dashboard または Guardian SDK を使用して、リソースを接続できます。
##### Auth0 Dashboard を使用する
1. Auth0 のログインプロンプトにアクセスし、表示された code、または別のソースから取得した同様の base32 エンコードされたキーをコピーします。次の手順では、この code を認証アプリケーションに入力します。
2. コピーした code を、Guardian などの認証アプリケーションに追加します。
##### SDK を使用する
1. Guardian ライブラリをインポートします。
```swift lines theme={null}
import Guardian
```
2. codeジェネレーターを作成します。
```swift lines theme={null}
let codeGenerator = try Guardian.totp(
base32Secret: enrollmentCode, // ユーザーが入力した登録code
algorithm: .sha1 // TOTP で使用されるアルゴリズム
)
```
3. 生成されたcodeを取得します。
```swift lines theme={null}
codeGenerator.code()
```
#### ワンタイムcodeを入力
Auth0 のログインプロンプトで、前の手順で生成したcodeを入力します。
［続行］を選択すると、アプリケーションがユーザーの認証要素として追加されたことを示すメッセージが表示されます。
#### アプリでログインする
認証要素の登録が完了すると、ユーザーはアプリを使ってログインできます。まず、認証方法として Guardian アプリを選択します。
次に、本人確認のため、ログイン プロンプトにワンタイムcodeを入力します。
