/*
* Copyright 2025 Hirokazu Kobayashi
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.idp.server.authenticators.webauthn4j;
import java.util.Base64;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* WebAuthn credential data model representing a registered FIDO2 authenticator.
*
* This class stores credential information extracted from WebAuthn registration responses and
* manages authenticator metadata for subsequent authentication operations.
*
*
User Experience Impact Parameters
*
* The following parameters directly affect user authentication behavior and security policy:
*
*
1. Resident Key (rk)
*
*
*
* 2. Credential Protection Policy (credProtect)
*
*
*
* 3. User Verification (UV)
*
*
*
* 4. Authenticator Attachment
*
*
*
* 5. Transports
*
*
* - Purpose: Communication methods supported by authenticator
*
- Set by: Authenticator during registration
*
- Values: {@code ["usb", "nfc", "ble", "internal", "hybrid"]}
*
- User Impact:
*
* - Browser uses transports to optimize authenticator selection UI
*
- internal → Shows platform biometric prompt
*
- usb → Shows "Insert security key" prompt
*
- hybrid → Shows QR code for phone authentication
*
* - Note: Automatically detected by authenticator; server stores for UX optimization
*
*
* Configuration Responsibility Matrix
*
*
*
* | Parameter |
* Set by Server |
* Set by Client |
* Decided by Authenticator |
*
*
* | rk (Resident Key) |
* ✅ authenticatorSelection.residentKey |
* ❌ |
* ✅ (Final decision based on capability) |
*
*
* | credProtect |
* ❌ (Can validate after) |
* ✅ extensions.credProtect |
* ✅ (Final decision, may downgrade) |
*
*
* | userVerification |
* ✅ authenticatorSelection.userVerification |
* ❌ |
* ✅ (Must comply if capable) |
*
*
* | authenticatorAttachment |
* ✅ authenticatorSelection.authenticatorAttachment |
* ❌ |
* N/A |
*
*
* | transports |
* ❌ |
* ❌ |
* ✅ (Auto-detected) |
*
*
*
* Common User Experience Patterns
*
* Passwordless Login (High Security)
*
* {@code
* {
* "authenticatorSelection": {
* "residentKey": "required", // rk=true
* "userVerification": "required" // UV always required
* }
* }
* // Result: User taps key → Enters PIN/biometric → Authenticated
* }
*
* 2nd Factor (Security Key Only)
*
* {@code
* {
* "authenticatorSelection": {
* "residentKey": "discouraged", // rk=false
* "userVerification": "discouraged", // Presence only
* "authenticatorAttachment": "cross-platform"
* }
* }
* // Result: User enters username → Taps security key → Authenticated
* }
*
* Biometric-Only (Platform)
*
* {@code
* {
* "authenticatorSelection": {
* "residentKey": "required", // rk=true
* "userVerification": "required", // Biometric required
* "authenticatorAttachment": "platform"
* }
* }
* // Result: User sees biometric prompt → FaceID/TouchID → Authenticated
* }
*
* @see com.webauthn4j.data.extension.CredentialProtectionPolicy
* @see com.webauthn4j.data.AuthenticatorTransport
* @see W3C WebAuthn Level 2 Specification
* @see FIDO
* CTAP2 credProtect Extension
*/
public class WebAuthn4jCredential {
// Credential Identifier
String id;
// User Information
String userId;
String username;
String userDisplayName;
// Relying Party
String rpId;
// Core Authenticator Information
String aaguid;
String attestedCredentialData;
Integer signatureAlgorithm;
long signCount;
// Core WebAuthn Features
Boolean rk;
// WebAuthn Level 3: Backup Flags
Boolean backupEligible;
Boolean backupState;
// JSON: Authenticator metadata (transports, attachment)
Map authenticator;
// JSON: Attestation information (type, format)
Map attestation;
// JSON: WebAuthn extensions (credProtect, prf, largeBlob)
Map extensions;
// JSON: Device/registration context
Map device;
// JSON: Future extensions
Map metadata;
// Timestamps
Long createdAt;
Long updatedAt;
Long authenticatedAt;
private static final Base64.Decoder urlDecoder = Base64.getUrlDecoder();
public WebAuthn4jCredential() {
this.authenticator = new HashMap<>();
this.attestation = new HashMap<>();
this.extensions = new HashMap<>();
this.device = new HashMap<>();
this.metadata = new HashMap<>();
}
public WebAuthn4jCredential(
String id, String userId, String rpId, String attestedCredentialData, long signCount) {
this();
this.id = id;
this.userId = userId;
this.rpId = rpId;
this.attestedCredentialData = attestedCredentialData;
this.signCount = signCount;
}
public WebAuthn4jCredential(
String id,
String userId,
String username,
String userDisplayName,
String rpId,
String aaguid,
String attestedCredentialData,
Integer signatureAlgorithm,
long signCount,
Boolean rk,
Boolean backupEligible,
Boolean backupState,
Map authenticator,
Map attestation,
Map extensions,
Map device,
Map metadata,
Long createdAt,
Long updatedAt,
Long authenticatedAt) {
this.id = id;
this.userId = userId;
this.username = username;
this.userDisplayName = userDisplayName;
this.rpId = rpId;
this.aaguid = aaguid;
this.attestedCredentialData = attestedCredentialData;
this.signatureAlgorithm = signatureAlgorithm;
this.signCount = signCount;
this.rk = rk;
this.backupEligible = backupEligible;
this.backupState = backupState;
this.authenticator = authenticator != null ? authenticator : new HashMap<>();
this.attestation = attestation != null ? attestation : new HashMap<>();
this.extensions = extensions != null ? extensions : new HashMap<>();
this.device = device != null ? device : new HashMap<>();
this.metadata = metadata != null ? metadata : new HashMap<>();
this.createdAt = createdAt;
this.updatedAt = updatedAt;
this.authenticatedAt = authenticatedAt;
}
public String id() {
return id;
}
public byte[] idAsBytes() {
return urlDecoder.decode(id);
}
public String userId() {
return userId;
}
public String username() {
return username;
}
public String userDisplayName() {
return userDisplayName;
}
public String rpId() {
return rpId;
}
public String aaguid() {
return aaguid;
}
public String attestedCredentialData() {
return attestedCredentialData;
}
public byte[] attestedCredentialDataAsBytes() {
return urlDecoder.decode(attestedCredentialData);
}
public Integer signatureAlgorithm() {
return signatureAlgorithm;
}
public long signCount() {
return signCount;
}
public Boolean rk() {
return rk;
}
public Boolean backupEligible() {
return backupEligible;
}
public Boolean backupState() {
return backupState;
}
public Map authenticator() {
return authenticator;
}
public Map attestation() {
return attestation;
}
public Map extensions() {
return extensions;
}
public Map device() {
return device;
}
public Map metadata() {
return metadata;
}
// Convenience methods for commonly accessed fields from JSON
@SuppressWarnings("unchecked")
public List transports() {
Object transports = authenticator.get("transports");
if (transports instanceof List) {
return (List) transports;
}
return List.of();
}
public String attestationType() {
Object type = attestation.get("type");
return type != null ? type.toString() : null;
}
public Integer credProtect() {
Object credProtect = extensions.get("cred_protect");
if (credProtect instanceof Number) {
return ((Number) credProtect).intValue();
}
return null;
}
public Long createdAt() {
return createdAt;
}
public Long updatedAt() {
return updatedAt;
}
public Long authenticatedAt() {
return authenticatedAt;
}
public Map toMap() {
Map result = new HashMap<>();
result.put("id", id);
result.put("user_id", userId);
result.put("username", username);
result.put("user_display_name", userDisplayName);
result.put("rp_id", rpId);
result.put("aaguid", aaguid);
result.put("attested_credential_data", attestedCredentialData);
result.put("signature_algorithm", signatureAlgorithm);
result.put("sign_count", signCount);
result.put("rk", rk);
result.put("backup_eligible", backupEligible);
result.put("backup_state", backupState);
result.put("authenticator", authenticator);
result.put("attestation", attestation);
result.put("extensions", extensions);
result.put("device", device);
result.put("metadata", metadata);
result.put("created_at", createdAt);
result.put("updated_at", updatedAt);
result.put("authenticated_at", authenticatedAt);
return result;
}
}