Guardian.swift iOS SDK

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

Guardian.swift を使用すると、Auth0 の Guardian 多要素認証サービスを独自の iOS アプリに統合し、アプリ自体を第二の認証要素として機能させることができます。これにより、ユーザーはアプリからシームレスな 多要素認証 のメリットをすべて利用できます。詳しくは、Apple Push Notification Service の利用を開始する をご覧ください。

​

要件

• Guardianを使用するには、iOS 10以降とSwift 4.1が必要です。
• このSDKを使用するには、テナントのGuardianサービスに独自のプッシュ通知用資格情報を設定する必要があります。設定しないと、プッシュ通知を受信できません。詳しくは、MFAのプッシュ通知を設定するをご覧ください。

​

Guardian iOS SDK のインストール

​

CocoaPods

Guardian.swift は CocoaPods から利用できます。インストールするには、Podfile に次の行を追加してください。

pod 'Guardian', '~> 1.1.0'

​

Carthage

Cartfile に次の行を追加します。

github "auth0/Guardian.swift" ~> 1.1.0

​

Guardianのプッシュ通知を有効にする

1. Auth0 Dashboard > セキュリティ > Multi-factor Auth に移動します。
2. Push Notification をオンにします。
3. プッシュ通知を設定する。

​

使用状況

Guardian は SDK の中核となるコンポーネントです。SDK を利用するには、ライブラリをインポートします：

import Guardian

テナントのドメインを設定します。テナント用に設定している場合は、カスタムドメイン を使用することもできます:

let domain = "<tenant>.<region>.auth0.com"

​

登録

登録とは、第2認証要素とAuth0アカウントとのリンクです。アカウントを登録すると、アイデンティティの確認に必要な第2認証要素の提示が必要になります。まだアプリでプッシュ通知を使用していない場合や、プッシュ通知にあまりなじみがない場合は、詳しくは Apple Push Notification Service Overview を参照してください。

登録には、テナントドメインに加えて、次の情報が必要です。

Variable	Description
Enrollment URI	Guardian Web WidgetでスキャンしたQRコード、またはメールやSMSで送信された登録チケットにエンコードされている値。
APNS Token	デバイスのApple APNSトークン。64バイトを含む文字列 (16進形式) である必要があります。
Key Pair	Auth0 Guardianに対して自身のアイデンティティを証明するために使用するRSA (秘密鍵/公開鍵) のキーペア。

情報がそろったら、デバイスを登録できます。

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 では、署名鍵を生成するための便利なクラスが提供されています。

let signingKey = try DataRSAPrivateKey.new()

このキーはメモリ内にしか存在しませんが、Data形式で取得し、たとえば暗号化されたSQLiteDBに安全に保存できます。

// データを保存する
let data = signingKey.data
// 保存処理を実行する

// Storageから読み込む
let loadedKey = try DataRSAPrivateKey(data: data)

ただ、iOS Keychain に保存したいだけなら:

let signingKey = try KeychainRSAPrivateKey.new(with: "com.myapp.mytag")

上記の例では、キーが作成され、指定したタグの下に自動的に保存されます。取得する場合は、そのタグを使用できます。

let signingKey = try KeychainRSAPrivateKey(tag: "com.myapp.mytag")

検証用のキーは、たとえば任意の SigningKey から取得できます。

let verificationKey = try signingKey.verificationKey()

​

ログインリクエストを許可する

登録が完了すると、ユーザーが MFA で本人確認を行う必要があるたびに、プッシュ通知を受け取ります。Guardian には、APNs から受信したデータを解析し、すぐに使える Notification インスタンスを返すメソッドがあります。

if let notification = Guardian.notification(from: notificationPayload) {
    // Guardianのプッシュ通知を受信しました
}

通知インスタンスを取得したら、allow メソッドを使って認証リクエストを簡単に許可できます。また、以前に取得した登録済みデバイスの情報もいくつか必要です。登録情報が複数ある場合は、通知と同じ id (enrollmentId プロパティ) を持つものを見つける必要があります。

情報がそろったら、device パラメータには、プロトコル AuthenticatedDevice を実装する任意のオブジェクトを指定できます:

struct Authenticator: Guardian.AuthenticationDevice {
    let signingKey: SigningKey
    let localIdentifier: String
}

ローカル識別子はデバイスのローカル ID で、登録時にはデフォルトで UIDevice.current.identifierForVendor が使われます。あとは次を呼び出すだけです:

Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .allow(notification: notification)
        .start { result in
            switch result {
            case .success:
                // 認証リクエストが正常に許可されました
            case .failure(let cause):
                // エラーが発生しました。causeを確認して原因を調べてください
            }
        }

​

ログインリクエストを拒否する

認証リクエストを拒否するには、代わりに reject を呼び出します。必要に応じて、拒否理由を送信することもできます。拒否理由は Guardian のログに表示されます。

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 を無効にする場合など、登録を削除するには、次のリクエストを送信します。

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 または Management API を使用して、OTPをMFA認証要素として有効にできます。このオプションではQR codeは不要で、ユーザーは手動で登録できます。

ユーザーに登録を案内するには、Auth0 Dashboard > User Management > Users に移動してユーザーを選択します。次に、Details タブを開き、Multi-Factor Authentication セクションから登録招待を送信します。

​

リソースを接続する

Auth0 Dashboard または Guardian SDK を使って、リソースを接続できます。

Auth0 Dashboard を使用する

1. Auth0ログインプロンプトにアクセスし、表示されたコード、または別のソースから取得した同様のBase32エンコード済みキーをコピーします。次の手順で、このコードを認証アプリに入力します。

   

2. コピーしたコードを、Guardian などの認証アプリに追加します。

SDKを使用する

1. Guardianライブラリをインポートします。

   import Guardian
   

2. コードジェネレーターを作成します。

   let codeGenerator = try Guardian.totp(
   
      base32Secret: enrollmentCode,  // ユーザーが入力した登録コード
   
      algorithm: .sha1			// TOTPで使用するアルゴリズム
   
   )
   

3. 生成されたコードを取得します。

   codeGenerator.code()
   

​

ワンタイムコードを入力

Auth0 のログインプロンプトで、前の手順で生成したワンタイムコードを入力します。

Continueを選択すると、アプリケーションがお使いのユーザーの認証要素として追加されたことを示すメッセージが表示されます。

​

アプリでログインする

認証要素の登録が完了すると、ユーザーはアプリを使ってログインできるようになります。まず、認証方法として Guardian アプリを選択します。

次に、本人確認のため、ログインプロンプトにワンタイムコードを入力します。