Home
I'll translate this document into English, later.
This library provides you a way to handle WebAuthn flow easily.
https://www.w3.org/TR/webauthn/
- Token Binding
- Extensions
- BLE Authenticator
- BLE Roaming Service
- ES256
This library force to use resident-key
Beforehand, modify your Info.plist for FaceID permission.
Add Privacy - Face ID Usage Description (NSFaceIDUsageDescription) item, and write your purpose.
At first, compose your client object like following.
import WebAuthnKit
let userConsentUI = UserConsentUI(viewController: self)
let authenticator = InternalAuthenticator(ui: self.userConsentUI)
self.webAuthnClient = WebAuthnClient(
origin: "https://example.org",
authenticator: authenticator
)このように、最低限originとauthenticatorを設定する必要があります。
authenticatorについては後述します。
まず鍵の登録です。
Webブラウザの上で、JavaScriptを使ってWebAuthnの実装をするとき、以下のように記述されます。
// サーバーから受け取ったパラメータ
// 詳細は省略します。
var publicKey = {
challenge: new Uint8Array(...)
rp: { ... },
user: { ... },
}
navigator.credentials.create({ publicKey })
.then(function (newCredential) {
// 生成したパラメータをサーバーに送信して検証
}).catch(function (err) {
// エラー処理
}SwiftでWebAuthnKitを使って同様の処理をするには、以下のようにして下さい。
var options = PublicKeyCreationOptions()
options.challenge = [0x01, 0x02, ...]
options.rp.id = [0x01, 0x02, ...]
options.rp.name = "https://example.org"
client.create(options).then { credential in
// 生成したパラメータをサーバーに送信して検証
}.catch { error in
// エラー処理
}JavaScriptのAPIとほぼ同じように書くことが出来ます。
WebAuthnKitは PromiseKit を採用していて、WebAuthnClient のcreateメソッドはPromiseを返します。
PromiseKitを使った全体の流れは以下のように記述できるでしょう。
firstly {
YourServiceHTTPClient.getRegistrationOptions()
}.then { options in
fidoClient.create(options)
}.then { credential in
YourServiceHTTPClient.postdRegistrationCredential(credential)
}.done { resp
// 登録完了の旨をUIに反映
}.catch { error in
// ...エラー処理
}処理の途中で中断したい場合は以下のようにcancelメソッドを呼びます。
fidoClient.cancel()待機中のPromiseのエラーとして、WAKError.cancelledがディスパッチされます。
認証時も登録時と同じように、ほぼJavaScriptのAPIと同じような書き方が出来ます。
firstly {
YourServiceHTTPClient.getAuthenticationOptions()
}.then { options in
fidoClient.get(options)
}.then { assertion in
YourServiceHTTPClient.postAssertion(assertion)
}.done {
// 認証成功をUIに反映させる
}.catch { error in
// ...エラー処理
}全体の流れが把握できたところで、もう一度最初に戻り、省略した箇所を説明していきます。
let fidoClient = WebAuthnClient(
origin: "https://example.org",
authenticator: authenticator
)WebAuthnClient の初期化にはauthenticatorが必要でした。
WebAuthnKitは２つのtypeのauthenticatorを用意しています。
WebAuthn で利用できるAuthenticatorには、 ClientとAuthenticatorが同じデバイス上で動くタイプであるPlatform Authenticatorと、
Clientが、外部デバイスとしてのAuthenticator(YubiKeyのようなものをイメージしてください)と連動するタイプであるCross-Platform Authenticatorがあります。
WebAuthnKitでは、まずPlatformタイプのInternalAuthenticatorが用意されています。
iOSアプリ自体にClient,Authenticator両方が組み込まれます。鍵情報の保存にはKeyChainを使い、ユーザーの検証にはTouchIDやFaceIDのようなiOS固有の機能を利用します。
WebAuthn のCross-Platform Authenticatorでは以下の３つのトランスポートタイプが定義されています
- USB
- NFC
- BLE(Bluetooth LowEnergy)
iOSの制限もあるため、WebAuthnKitではBLEのみをサポートしています。
WebAuthnにおけるAuthenticatorは鍵の発行や管理、ユーザーのVerificationやPresenceの確認などの責務を持ちます。