Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lyokato/WebAuthnKit-Android
WebAuthn Android Library
https://github.com/lyokato/WebAuthnKit-Android
Last synced: about 2 months ago
JSON representation
WebAuthn Android Library
- Host: GitHub
- URL: https://github.com/lyokato/WebAuthnKit-Android
- Owner: lyokato
- License: mit
- Created: 2019-01-17T07:48:49.000Z (almost 6 years ago)
- Default Branch: develop
- Last Pushed: 2019-02-13T14:54:59.000Z (almost 6 years ago)
- Last Synced: 2024-04-03T01:01:32.731Z (9 months ago)
- Language: Kotlin
- Homepage:
- Size: 416 KB
- Stars: 26
- Watchers: 2
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-fido2 - lyokato/WebAuthnKit-Android
README
# WebAuthnKit (Android)
This library provides you a way to handle W3C Web Authentication API (a.k.a. WebAuthN / FIDO 2.0) easily.
(You can also get iOS version here https://github.com/lyokato/WebAuthnKit-iOS )
## Attention
THIS VERSION IS NOT STABLE YET
This library doens't work as expected on Android5 currently.
## Installation
In your application's build.gradle
```gradle
dependencies {
implementation 'webauthnkit:webauthnkit-core:0.9.3'
}
```
pom
```xml
webauthnkit
webauthnkit-core
0.9.3
pom
```
## Getting Started
### AutoBackup setting
Make sure to exclude 'webauthnkit.db'
- AndroidManifest.xml
```xml
```
- values/backup_rules.xml
```xml
```
Or you can set allowBackup="false" simply.
```xml
```
### Activity
WebAuthnKit uses Kotlin's experimental features.
So, add some annotations on your Activity.
`FragmentActivity` is required to be bound with WebAuthnKit's UI features.
Of cource, `androidx.appcompat.app.AppCompatActivity` is also OK.
```kotlin
@ExperimentalCoroutinesApi
@ExperimentalUnsignedTypes
class AuthenticationActivity : AppCompatActivity() {
//...
}
```
### Setup your WebAuthnClient
At first, prepare UserConsentUI on your Activity.
```kotlin
import webauthnkit.core.authenticator.internal.ui.UserConsentUI
import webauthnkit.core.authenticator.internal.ui.UserConsentUIFactory
var consentUI: UserConsentUI? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
consentUI = UserConsentUIFactory.create(this)
// You can configure consent-ui here
// consentUI.config.registrationDialogTitle = "New Login Key"
// consentUI.config.selectionDialogTitle = "Select Key"
// ...
}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
consentUI?.onActivityResult(requestCode, resultCode, data)
}
```
Then, create WebAuthnClient
```kotlin
import webauthnkit.core.client.WebAuthnClient
val client = WebAuthnClient.create(
activity = this,
origin = "https://example.org"
ui = consentUI!!
)
// You can configure client here
// client.maxTimeout = 120
// client.defaultTimeout = 60
```
### 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
```kotlin
private suspend fun executeRegistration() {
val options = PublicKeyCredentialCreationOptions()
options.challenge = ByteArrayUtil.fromHex(challenge)
options.user.id = userId
options.user.name = username
options.user.displayName = userDisplayName
options.user.icon = userIconURL
options.rp.id = "https://example.org"
options.rp.name = "your_service_name"
options.rp.icon = yourServiceIconURL
options.attestation = attestationConveyance
options.addPubKeyCredParam(
alg = COSEAlgorithmIdentifier.es256
)
options.authenticatorSelection = AuthenticatorSelectionCriteria(
requireResidentKey = true,
userVerification = userVerification
)
try {
val credential = client.create(options)
// send parameters to your server
// credential.id
// credential.rawId
// credential.response.attestationObject
// credential.response.clientDataJSON
} catch (e: Exception) {
// error handling
}
}
```
If you would like to stop while client is in progress, you can call cancel method.
```kotlin
client.cancel()
```
`webauthnkit.core.CancelledException` will be thrown in your suspend function.
### 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
```kotlin
private suspend fun executeAuthentication() {
val options = PublicKeyCredentialRequestOptions()
options.challenge = ByteArrayUtil.fromHex(challenge)
options.rpId = relyingParty
options.userVerification = userVerification
if (credId.isNotEmpty()) {
options.addAllowCredential(
credentialId = ByteArrayUtil.fromHex(credId),
transports = mutableListOf(AuthenticatorTransport.Internal))
}
try {
val assertion = client.get(options)
// send parameters to your server
//assertion.id
//assertion.rawId
//assertion.response.authenticatorData
//assertion.response.signature
//assertion.response.userHandle
//assertion.response.clientDataJSON
} catch (e: Exception) {
// error handling
}
}
```
## Features
### Not Implemented yet
- Token Binding
- Extensions
- BLE Authenticator
- BLE Roaming Service
- SafetyNet Attestation
### Key Algorithm Support
- ES256
### Resident Key
InternalAuthenticator forces to use resident-key.
### Attestation
Currently, this library supports only self-attestation.
## 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