Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lyokato/WebAuthnKit-iOS
WebAuthn iOS Library
https://github.com/lyokato/WebAuthnKit-iOS
Last synced: about 1 month ago
JSON representation
WebAuthn iOS Library
- Host: GitHub
- URL: https://github.com/lyokato/WebAuthnKit-iOS
- Owner: lyokato
- License: mit
- Created: 2018-11-20T11:19:38.000Z (about 6 years ago)
- Default Branch: develop
- Last Pushed: 2022-05-08T16:38:48.000Z (over 2 years ago)
- Last Synced: 2024-05-18T06:41:14.402Z (7 months ago)
- Language: Swift
- Homepage:
- Size: 184 KB
- Stars: 99
- Watchers: 5
- Forks: 28
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-webauthn - Lyo Kato: iOS Webauthn Kit - This library provides you a way to handle W3C Web Authentication API (a.k.a. WebAuthN / FIDO 2.0) easily. (Client Libraries)
- awesome-fido2 - lyokato/WebAuthnKit-iOS
README
# 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
```ruby
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '11.0'
use_frameworks!
target '' 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.
```swift
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
```swift
var options = PublicKeyCredentialCreationOptions()
options.challenge = Bytes.fromHex(challenge) // must be Array
options.user.id = Bytes.fromString(userId) // must be Array
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.
```swift
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.
```swift
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
```swift
var options = PublicKeyCredentialRequestOptions()
options.challenge = Bytes.fromHex(challenge) // must be Array
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.
```swift
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