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: userConsentUI)
self.webAuthnClient = WebAuthnClient(
origin: "https://example.org",
authenticator: authenticator
)With a flow which is described in following documents, WebAuthnClient creates a credential if success.
var options = PublicKeyCredentialCreationOptions()
options.challenge = Bytes.fromHex(challenge) // must be Array<UInt8>
options.user.id = Bytes.fromString(userId) // must be Array<UInt8>
options.user.name = userName
options.user.displayName = displayName
options.user.icon = iconURL // Optional
options.rp.id = "https://example.org"
options.rp.name = "your_service_name"
options.rp.icon = yourServiceIconURL // Optional
options.attestation = .required // (choose from .required, .preferred, .discouraged)
options.addPubKeyCredParam(alg: .es256)
options.authenticatorSelection = AuthenticatorSelectionCriteria(
requireResidentKey: requireResidentKey, // this flag is ignored by InternalAuthenticator
userVerification: verification
)
client.create(options).then { credential in
// sent parameters to your server
}.catch { error in
// error handling
}Each option-parameter corresponds to JavaScript API implemented on web-browsers.
WebAuthnKit currently adopt PromiseKit, so, whole registration process can be written like this.
firstly {
self.yourServiceHTTPClient.getRegistrationOptions()
}.then { response in
let options = self.createOptionsFromResponse(response)
self.webAuthnClient.create(options)
}.then { credential in
let requet = self.createHTTPRequestFromCredential(credential)
self.yourServiceHTTPClient.postdRegistrationCredential(request)
}.done { resp
// show completion message on UI
}.catch { error in
// error handling
}処理の途中で中断したい場合は以下のように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の確認などの責務を持ちます。