WebAuthnKit (iOS)

This library provides you a way to handle W3C Web Authentication API (a.k.a. WebAuthN / FIDO 2.0) easily.

(You can also get Android version here https://github.com/lyokato/WebAuthnKit-Android)

Demo App

Installation

CocoaPods

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '11.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'WebAuthnKit', '~> 0.9.6'
end

$ pod install

Getting Started

Info.plist

Beforehand, modify your Info.plist for FaceID permission.

Add Privacy - Face ID Usage Description (NSFaceIDUsageDescription) item, and write your purpose.

Setup your WebAuthnClient

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
)

Registration Flow

With a flow which is described in following documents, WebAuthnClient creates a credential if it succeeded.

• https://www.w3.org/TR/webauthn/#createCredential
• https://www.w3.org/TR/webauthn/#op-make-cred

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 = .direct // (choose from .direct, .indirect, .none)
options.addPubKeyCredParam(alg: .es256)
options.authenticatorSelection = AuthenticatorSelectionCriteria(
    requireResidentKey: true, // this flag is ignored by InternalAuthenticator
    userVerification: .required // (choose from .required, .preferred, .discouraged)
)

self.webAuthnClient.create(options).then { credential in
  // send parameters to your server

  // credential.id
  // credential.rawId
  // credential.response.attestationObject
  // credential.response.clientDataJSON

}.catch { error in
  // error handling
}

Each option-parameter corresponds to JavaScript API implemented on web-browsers.

Flow with PromiseKit

WebAuthnKit currently adopt PromiseKit, so, whole registration process can be written like this.

import PromiseKit

firstly {

  self.yourServiceHTTPClient.getRegistrationOptions()

}.then { response in

  let options = self.createCreationOptionsFromHTTPResponse(response)
  self.webAuthnClient.create(options)

}.then { credential in

  let request = self.createHTTPRequestFromCredential(credential)
  self.yourServiceHTTPClient.postdRegistrationCredential(request)

}.done { resp

   // show completion message on UI

}.catch { error in

  // error handling

}

If you would like to stop while client is in progress, you can call cancel method.

self.webAuthnClient.cancel()

WAKError.cancelled will be dispatched as an Error of waiting Promise.

Authentication Flow

With a flow which is described in following documents, WebAuthnClient finds credentials, let user to select one (if multiple), and signs the response with it.

• https://www.w3.org/TR/webauthn/#getAssertion
• https://www.w3.org/TR/webauthn/#op-get-assertion

var options = PublicKeyCredentialRequestOptions()
options.challenge = Bytes.fromHex(challenge) // must be Array<UInt8>
options.rpId = "https://example.org"
options.userVerification = .required // (choose from .required, .preferred, .discouraged)
options.addAllowCredential(
    credentialId: Bytes.fromHex(credId),
    transports:   [.internal_]
)

self.webAuthnClient.get(options).then { assertion in
  // send parameters to your server

  // assertion.id
  // assertion.rawId
  // assertion.response.authenticatorData
  // assertion.response.signature
  // assertion.response.userHandle
  // assertion.response.clientDataJSON

}.catch {
  // error handling
}

You may want to write whole assertion process like following.

firstly {

  self.yourServiceHTTPClient.getAuthenticationOptions()

}.then { response in

  let options = self.createRequestOptionsFromHTTPResponse(response)
  self.webAuthnClient.get(options)

}.then { assertion in

  let request = self.createHTTPRequestFromAssertion(assertion)
  self.yourServiceHTTPClient.postAssertion(request)

}.done {

  // show completion message on UI

}.catch { error in

  // error handling

}

Features

Not implemented yet

• [ ] Token Binding
• [ ] Extensions
• [ ] BLE Authenticator
• [ ] BLE Roaming Service

Key Algorithm Support

• ES256

Resident Key

InternalAuthenticator forces to use resident-key.

See Also

• https://www.w3.org/TR/webauthn/
• https://fidoalliance.org/specs/fido-v2.0-rd-20170927/fido-client-to-authenticator-protocol-v2.0-rd-20170927.html

License

MIT-LICENSE

Author

Lyo Kato