mirror of
https://github.com/sonr-io/sonr.git
synced 2026-08-03 18:01:39 +00:00
Prad Nukala
@@ -0,0 +1,191 @@
|
||||
---
|
||||
title: "Migrating from Centralized to Decentralized Authentication"
|
||||
description: "A comprehensive guide to migrating from centralized 8787 endpoints to decentralized OIDC authentication with WebAuthn"
|
||||
sidebarTitle: "Decentralized Authentication"
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
# Migrating from Centralized to Decentralized Authentication
|
||||
|
||||
## Overview
|
||||
|
||||
Sonr is transitioning from a centralized authentication model using 8787 endpoints to a fully decentralized, privacy-preserving authentication system leveraging OpenID Connect (OIDC), Self-Issued OpenID Provider (SIOP), and WebAuthn technologies.
|
||||
|
||||
### Key Improvements
|
||||
|
||||
- **Decentralization**: Move from centralized identity management to self-sovereign identity
|
||||
- **WebAuthn Integration**: Hardware-backed, phishing-resistance authentication
|
||||
- **Gasless Onboarding**: Zero-cost user registration and transactions
|
||||
- **Automatic Vault Creation**: Seamless user experience with instant identity setup
|
||||
- **Enhanced Privacy**: DID-based authentication with verifiable presentations
|
||||
|
||||
## Architecture Comparison
|
||||
|
||||
### Old Architecture: Centralized 8787 Endpoints
|
||||
|
||||
- Centralized authentication server
|
||||
- Fixed credential storage
|
||||
- Limited authentication methods
|
||||
- Higher security risks
|
||||
|
||||
### New Architecture: Decentralized OIDC Provider
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[User Device] --> B{WebAuthn Registration}
|
||||
B --> |Credential Generation| C[Blockchain Bridge]
|
||||
C --> |Broadcast Credential| D[Sonr Blockchain]
|
||||
D --> |Create DID| E[User's Decentralized Identity]
|
||||
E --> |SIOP Flow| F[OIDC Provider]
|
||||
F --> |Verifiable Presentation| G[Service Provider]
|
||||
```
|
||||
|
||||
## Migration Steps
|
||||
|
||||
### 1. Prerequisites
|
||||
|
||||
- Go 1.24.1+
|
||||
- Cosmos SDK v0.50.14
|
||||
- WebAuthn-compatible browser/device
|
||||
- Updated Sonr SDK
|
||||
|
||||
### 2. Configuration Changes
|
||||
|
||||
#### Environment Variables
|
||||
|
||||
<CodeGroup>
|
||||
```bash title="Old Configuration"
|
||||
# Centralized auth endpoints
|
||||
AUTH_ENDPOINT=https://8787.sonr.io/auth
|
||||
AUTH_CLIENT_ID=legacy-client-id
|
||||
```
|
||||
|
||||
```bash title="New Configuration"
|
||||
# Decentralized OIDC configuration
|
||||
OIDC_PROVIDER_URL=https://oidc.sonr.network
|
||||
WEBAUTHN_ORIGIN=https://your-app.com
|
||||
DID_RESOLVER_URL=https://did.sonr.network
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
### 3. Endpoint Migration
|
||||
|
||||
| Old Endpoint | New Endpoint | Changes |
|
||||
| ---------------- | -------------------- | ----------------------- |
|
||||
| `/auth/login` | `/oidc/authorize` | OIDC authorization flow |
|
||||
| `/auth/register` | `/webauthn/register` | WebAuthn registration |
|
||||
| `/auth/token` | `/oidc/token` | Token issuance via SIOP |
|
||||
|
||||
### 4. API Changes
|
||||
|
||||
#### Request Format
|
||||
|
||||
<CodeGroup>
|
||||
```json title="Legacy Request"
|
||||
{
|
||||
"username": "user@example.com",
|
||||
"password": "legacy-password"
|
||||
}
|
||||
```
|
||||
|
||||
```json title="New WebAuthn Request"
|
||||
{
|
||||
"challenge": "base64-encoded-challenge",
|
||||
"attestation": {
|
||||
"type": "public-key",
|
||||
"id": "credential-id",
|
||||
"rawId": "base64-encoded-raw-credential",
|
||||
"response": {
|
||||
"clientDataJSON": "...",
|
||||
"attestationObject": "..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
### 5. WebAuthn Integration
|
||||
|
||||
#### Registration Flow
|
||||
|
||||
1. Generate registration challenge
|
||||
2. Create WebAuthn credential
|
||||
3. Broadcast credential to blockchain
|
||||
4. Automatically create user vault
|
||||
5. Issue decentralized identifier (DID)
|
||||
|
||||
#### Code Example
|
||||
|
||||
```go title="WebAuthn Registration Handler"
|
||||
func (s *Server) HandleWebAuthnRegistration(w http.ResponseWriter, r *http.Request) {
|
||||
// 1. Validate WebAuthn attestation
|
||||
credential, err := s.webAuthnService.VerifyRegistration(attestationData)
|
||||
|
||||
// 2. Broadcast to blockchain
|
||||
didDoc, err := s.blockchainBridge.CreateDID(credential)
|
||||
|
||||
// 3. Create user vault
|
||||
vault, err := s.vaultService.CreateVault(didDoc)
|
||||
|
||||
// 4. Issue OIDC token
|
||||
token := s.oidcService.IssueToken(didDoc)
|
||||
}
|
||||
```
|
||||
|
||||
### 6. SIOP (Self-Issued OpenID Provider)
|
||||
|
||||
#### Key Concepts
|
||||
|
||||
- Verifiable Presentations
|
||||
- Decentralized Identifiers (DIDs)
|
||||
- User-controlled authentication
|
||||
|
||||
### 7. Error Handling
|
||||
|
||||
#### Migration Errors
|
||||
|
||||
| Error Code | Description | Mitigation |
|
||||
| ------------------------ | ---------------------- | -------------------- |
|
||||
| `AUTH_LEGACY_DEPRECATED` | Legacy auth method | Upgrade client |
|
||||
| `WEBAUTHN_UNSUPPORTED` | Device incompatibility | Use alternative auth |
|
||||
| `DID_RESOLUTION_FAILED` | Identity verification | Retry registration |
|
||||
|
||||
### 8. Testing Migration
|
||||
|
||||
```bash
|
||||
# Validate WebAuthn registration
|
||||
sonr webauthn test-registration
|
||||
|
||||
# Verify OIDC provider
|
||||
sonr oidc validate-provider
|
||||
|
||||
# Check DID resolution
|
||||
sonr did resolve did:sonr:example
|
||||
```
|
||||
|
||||
### 9. Breaking Changes
|
||||
|
||||
- Legacy password authentication removed
|
||||
- Token format changed to JWT with DID claims
|
||||
- New client libraries required
|
||||
- WebAuthn mandatory for registration
|
||||
|
||||
## Rollback Procedure
|
||||
|
||||
If issues arise:
|
||||
|
||||
1. Maintain legacy user mappings
|
||||
2. Provide fallback authentication
|
||||
3. Gradual, opt-in migration
|
||||
|
||||
## Conclusion
|
||||
|
||||
This migration represents a significant leap in authentication security and user privacy. By adopting WebAuthn, SIOP, and blockchain-backed identities, we're creating a more robust, user-controlled authentication ecosystem.
|
||||
|
||||
## Support
|
||||
|
||||
- [Sonr Developer Docs](/docs)
|
||||
- [WebAuthn Specification](https://www.w3.org/TR/webauthn-2/)
|
||||
- [OIDC Community](https://openid.net/developers/specs/)
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
title: "DID Generation and Management"
|
||||
description: "Learn how to generate and manage Decentralized Identifiers (DIDs) using advanced crypto interfaces"
|
||||
sidebarTitle: "Identity Generation"
|
||||
icon: "signature"
|
||||
---
|
||||
|
||||
# DID Generation Patterns
|
||||
|
||||
The Sonr project provides a robust and flexible DID (Decentralized Identifier) generation system supporting multiple key types and cryptographic methods.
|
||||
|
||||
## Supported Key Types
|
||||
|
||||
The `didkey.go` interface supports the following key types:
|
||||
|
||||
- RSA Public Keys
|
||||
- Ed25519 Public Keys
|
||||
- Secp256k1 Public Keys
|
||||
|
||||
## Basic DID Generation
|
||||
|
||||
### Creating a DID from a Public Key
|
||||
|
||||
```go
|
||||
import (
|
||||
"github.com/libp2p/go-libp2p/core/crypto"
|
||||
"github.com/sonr-io/sonr/crypto/keys"
|
||||
)
|
||||
|
||||
// Generate a new key pair
|
||||
privateKey, publicKey, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)
|
||||
|
||||
// Create a DID
|
||||
did, err := keys.NewDID(publicKey)
|
||||
```
|
||||
|
||||
### Parsing an Existing DID
|
||||
|
||||
```go
|
||||
// Parse a DID string
|
||||
did, err := keys.Parse("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGTsyDFWYviJr4")
|
||||
```
|
||||
|
||||
## Advanced DID Operations
|
||||
|
||||
### Address Derivation
|
||||
|
||||
```go
|
||||
// Get a blockchain-compatible address from a DID
|
||||
address, err := did.Address()
|
||||
```
|
||||
|
||||
### Compressed Public Key Retrieval
|
||||
|
||||
```go
|
||||
// Get a compressed public key (for Secp256k1)
|
||||
compressedPubKey, err := did.CompressedPubKey()
|
||||
```
|
||||
|
||||
## MPC Enclave DID Generation
|
||||
|
||||
For MPC (Multi-Party Computation) enclaves, use a specialized method:
|
||||
|
||||
```go
|
||||
// Create a DID from MPC enclave public key bytes
|
||||
did, err := keys.NewFromMPCPubKey(enclavePublicKeyBytes)
|
||||
```
|
||||
|
||||
## DID Validation
|
||||
|
||||
```go
|
||||
// Validate a DID format
|
||||
err := keys.ValidateFormat("did:key:example123")
|
||||
```
|
||||
|
||||
## Multicodec Support
|
||||
|
||||
The library supports various multicodec prefixes for different key types:
|
||||
|
||||
- RSA: `0x1205`
|
||||
- Ed25519: `0xed`
|
||||
- Secp256k1: `0xe7`
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Always generate keys using cryptographically secure methods
|
||||
- Validate DIDs before using them in critical operations
|
||||
- Use the appropriate key type for your security requirements
|
||||
|
||||
## Example: Complete DID Workflow
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"github.com/libp2p/go-libp2p/core/crypto"
|
||||
"github.com/sonr-io/sonr/crypto/keys"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// Generate a new key pair
|
||||
privateKey, publicKey, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Create a DID
|
||||
did, err := keys.NewDID(publicKey)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Get the DID string
|
||||
didString := did.String()
|
||||
fmt.Println("Generated DID:", didString)
|
||||
|
||||
// Derive blockchain address
|
||||
address, err := did.Address()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
fmt.Println("Blockchain Address:", address)
|
||||
}
|
||||
```
|
||||
|
||||
## Compatibility and Interoperability
|
||||
|
||||
The Sonr DID implementation follows the W3C DID specification, ensuring broad compatibility with other decentralized identity systems.
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: "DWN Plugin Architecture"
|
||||
description: "Deep dive into the Decentralized Web Node (DWN) plugin system and integration"
|
||||
sidebarTitle: "WASM Architecture"
|
||||
icon: "puzzle"
|
||||
---
|
||||
|
||||
# DWN Plugin Architecture
|
||||
|
||||
The Sonr project implements a flexible and secure plugin system for Decentralized Web Nodes (DWN), enabling modular and extensible functionality.
|
||||
|
||||
## Overview
|
||||
|
||||
The plugin architecture is designed to:
|
||||
|
||||
- Support dynamic loading of WebAssembly (WASM) plugins
|
||||
- Provide a standardized interface for plugin interactions
|
||||
- Enable secure, isolated execution of plugins
|
||||
|
||||
## Core Components
|
||||
|
||||
### Plugin Manager
|
||||
|
||||
The `PluginManager` manages plugin lifecycle and interactions:
|
||||
|
||||
```go
|
||||
type PluginManager struct {
|
||||
plugins map[string]Plugin
|
||||
actors map[string]Actor
|
||||
}
|
||||
|
||||
type Plugin interface {
|
||||
Initialize(config map[string]any) error
|
||||
Execute(method string, payload []byte) ([]byte, error)
|
||||
Close() error
|
||||
}
|
||||
```
|
||||
|
||||
### Plugin Configuration
|
||||
|
||||
Plugins are configured through a structured configuration:
|
||||
|
||||
```go
|
||||
type PluginConfig struct {
|
||||
ID string // Unique plugin identifier
|
||||
Type string // Plugin type (e.g., "motor", "crypto")
|
||||
Path string // WASM module path
|
||||
Environment map[string]any // Plugin-specific environment variables
|
||||
}
|
||||
```
|
||||
|
||||
## Loading and Initializing Plugins
|
||||
|
||||
### Basic Plugin Loading
|
||||
|
||||
```go
|
||||
func (pm *PluginManager) LoadPlugin(config PluginConfig) error {
|
||||
// Load WASM module
|
||||
module, err := extism.Load(config.Path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// Initialize plugin
|
||||
plugin := &WASMPlugin{
|
||||
module: module,
|
||||
config: config,
|
||||
}
|
||||
|
||||
// Store in plugin registry
|
||||
pm.plugins[config.ID] = plugin
|
||||
}
|
||||
```
|
||||
|
||||
### Actor-Based Plugin Management
|
||||
|
||||
```go
|
||||
func (pm *PluginManager) CreateActor(pluginID string) (*Actor, error) {
|
||||
plugin, exists := pm.plugins[pluginID]
|
||||
if !exists {
|
||||
return nil, errors.New("plugin not found")
|
||||
}
|
||||
|
||||
actor := NewActor(plugin)
|
||||
pm.actors[actor.ID] = actor
|
||||
|
||||
return actor, nil
|
||||
}
|
||||
```
|
||||
|
||||
## Plugin Execution Workflow
|
||||
|
||||
1. Plugin is loaded from WASM module
|
||||
2. Configuration is applied
|
||||
3. Plugin is initialized
|
||||
4. Specific methods can be invoked through a standardized interface
|
||||
|
||||
### Example Plugin Execution
|
||||
|
||||
```go
|
||||
func ExecutePluginMethod(pluginID, method string, payload []byte) ([]byte, error) {
|
||||
plugin := pluginManager.plugins[pluginID]
|
||||
return plugin.Execute(method, payload)
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration and Environment
|
||||
|
||||
### Plugin Environment Variables
|
||||
|
||||
```json
|
||||
{
|
||||
"motor_plugin": {
|
||||
"enclave_config": { ... },
|
||||
"chain_id": "sonr-testnet-1",
|
||||
"log_level": "debug"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling and Logging
|
||||
|
||||
```go
|
||||
type PluginError struct {
|
||||
Code string
|
||||
Message string
|
||||
Details map[string]any
|
||||
}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- WASM plugins run in an isolated sandbox
|
||||
- Limited access to system resources
|
||||
- Runtime restrictions prevent malicious behavior
|
||||
- Cryptographic verification of plugin modules
|
||||
|
||||
## Plugin Types
|
||||
|
||||
1. **Crypto Plugins**: Cryptographic operations
|
||||
2. **Motor Plugins**: MPC and token management
|
||||
3. **DID Plugins**: Decentralized Identity operations
|
||||
4. **Custom Plugins**: Application-specific extensions
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Keep plugins small and focused
|
||||
- Use standardized interfaces
|
||||
- Implement comprehensive error handling
|
||||
- Validate all plugin inputs
|
||||
- Monitor plugin performance
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
For advanced plugin configuration and deployment, refer to the [PDK Configuration Guide](/blockchain/modules/dwn/configuration).
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Delegated Proof of Stake (DPoS)
|
||||
description: A decentralized, secure, and efficient consensus mechanism.
|
||||
---
|
||||
|
||||
Sonr leverages a Delegated Proof of Stake (DPoS) mechanism to optimize network security and user participation. DPoS imposes an opportunity cost for malicious behavior through slashing, but it also presents challenges that must be addressed for a sustainable design.
|
||||
|
||||
## Challenges in Staking Mechanisms
|
||||
|
||||
- **Token Value**: The token must have intrinsic value to incentivize staking.
|
||||
- **Wealth Concentration**: Staking can give an outsized advantage to wealthy users.
|
||||
- **Coordination Problems**: Staking mechanisms can be gamed by coordinated actors.
|
||||
|
||||
## Sonr's Approach to DPoS
|
||||
|
||||
We have designed our staking mechanism to address these challenges and create a sustainable and equitable system:
|
||||
|
||||
<CardGroup>
|
||||
<Card title="Low Barrier to Entry">
|
||||
The upfront capital required to stake is designed to not significantly
|
||||
discourage participation.
|
||||
</Card>
|
||||
<Card title="Slashing for Malice">
|
||||
If a stakeholder group makes decisions that materially harm the network,
|
||||
their stake is slashed.
|
||||
</Card>
|
||||
<Card title="Incentivizing Positive Growth">
|
||||
Stakeholders can make decisions that positively impact the future network
|
||||
health and token price, promoting long-term growth.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Network Architecture
|
||||
description: A detailed look at Sonr's three-tier system design.
|
||||
---
|
||||
|
||||
Our incorporation of embedded light nodes signifies a strategic move towards enhancing network robustness and efficiency. These nodes operate with a reduced resource footprint, ensuring a widespread and seamless network distribution. They form the bedrock of the infrastructure, interfacing directly with a series of validators. These validators are pivotal in maintaining the integrity and trustworthiness of the network, each playing an instrumental role in processing transactions and securing the network's protocol.
|
||||
|
||||
## Blockchain Services
|
||||
|
||||
Blockchain Services are instrumental in ensuring seamless interoperability and data exchange across the network.
|
||||
|
||||
<CardGroup>
|
||||
<Card title="IBC Relayer">
|
||||
The IBC Relayer stands at the forefront of inter-blockchain communication,
|
||||
enabling different blockchain protocols to transfer and share information
|
||||
effectively.
|
||||
</Card>
|
||||
<Card title="IPFS/Libp2p Routing">
|
||||
IPFS/Libp2p Routing underpins the decentralized routing of information,
|
||||
ensuring resilient and scalable data distribution across the network.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Interoperability Protocols
|
||||
|
||||
The overarching network architecture is designed with interoperability at its core, integrating protocols such as Matrix and Pinecone to facilitate communication and data exchange across disparate systems.
|
||||
|
||||
- **Matrix Protocol**: A new paradigm in secure, decentralized communication.
|
||||
- **Pinecone Routing**: A novel approach to establishing network pathways, enhancing the efficiency and reliability of data transmission.
|
||||
@@ -0,0 +1,238 @@
|
||||
---
|
||||
title: "WebAuthn Integration"
|
||||
description: "Comprehensive guide to Sonr's WebAuthn/FIDO2 implementation for passwordless authentication"
|
||||
icon: "key"
|
||||
sidebarTitle: "WebAuthn Integration"
|
||||
---
|
||||
|
||||
<Note>
|
||||
This documentation covers the WebAuthn implementation in the Sonr blockchain,
|
||||
providing a secure, passwordless authentication mechanism through
|
||||
W3C-compliant WebAuthn protocols.
|
||||
</Note>
|
||||
|
||||
## Overview
|
||||
|
||||
Sonr's WebAuthn implementation enables gasless onboarding and secure transaction authorization without requiring users to hold tokens initially. This document provides a comprehensive guide to understanding and using our WebAuthn client.
|
||||
|
||||
## Architecture
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="https://cdn.sonr.io/diagrams/passkey-jwt.png"
|
||||
alt="WebAuthn Architecture Diagram"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
The WebAuthn implementation is structured across three primary layers:
|
||||
|
||||
1. **Client Layer** (`client/auth/webauthn.go`)
|
||||
|
||||
- WebAuthnClient interface
|
||||
- Registration and Authentication flows
|
||||
- DID integration
|
||||
|
||||
2. **Internal WebAuthn Package** (`internal/webauthn/`)
|
||||
|
||||
- COSE key parsing
|
||||
- CBOR encoding/decoding
|
||||
- Attestation verification
|
||||
- Signature verification (ES256/RS256)
|
||||
|
||||
3. **DID Module Layer** (`x/did/keeper/`)
|
||||
- WebAuthn controller verifier
|
||||
- Credential storage in DID documents
|
||||
- Challenge generation and validation
|
||||
|
||||
## API Reference
|
||||
|
||||
### WebAuthnClient Interface
|
||||
|
||||
<CodeGroup>
|
||||
```go
|
||||
type WebAuthnClient interface {
|
||||
// Registration Operations
|
||||
BeginRegistration(ctx context.Context, opts *RegistrationOptions) (*RegistrationChallenge, error)
|
||||
CompleteRegistration(ctx context.Context, challenge *RegistrationChallenge, response *AuthenticatorAttestationResponse) (*WebAuthnCredential, error)
|
||||
|
||||
// Authentication Operations
|
||||
BeginAuthentication(ctx context.Context, opts *AuthenticationOptions) (*AuthenticationChallenge, error)
|
||||
CompleteAuthentication(ctx context.Context, challenge *AuthenticationChallenge, response *AuthenticatorAssertionResponse, credentialID string) (*AuthenticationResult, error)
|
||||
|
||||
// Credential Management Methods...
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Registration Flow
|
||||
|
||||
<CodeGroup>
|
||||
```go Registration Example
|
||||
func registerWebAuthn() error {
|
||||
client := auth.NewWebAuthnClient()
|
||||
ctx := context.Background()
|
||||
|
||||
// Begin registration
|
||||
regOpts := &auth.RegistrationOptions{
|
||||
UserID: "user123",
|
||||
Username: "alice@example.com",
|
||||
DisplayName: "Alice Smith",
|
||||
UserVerification: "preferred",
|
||||
}
|
||||
|
||||
challenge, err := client.BeginRegistration(ctx, regOpts)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// Complete registration
|
||||
response := &auth.AuthenticatorAttestationResponse{
|
||||
ClientDataJSON: clientDataJSON,
|
||||
AttestationObject: attestationObject,
|
||||
}
|
||||
|
||||
credential, err := client.CompleteRegistration(ctx, challenge, response)
|
||||
return err
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
<CodeGroup>
|
||||
```go Authentication Example
|
||||
func authenticateWebAuthn(credentialID string) error {
|
||||
client := auth.NewWebAuthnClient()
|
||||
ctx := context.Background()
|
||||
|
||||
// Begin authentication
|
||||
authOpts := &auth.AuthenticationOptions{
|
||||
UserVerification: "required",
|
||||
AllowedCredentials: []*auth.CredentialDescriptor{
|
||||
{
|
||||
Type: "public-key",
|
||||
ID: []byte(credentialID),
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
challenge, err := client.BeginAuthentication(ctx, authOpts)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// Complete authentication
|
||||
response := &auth.AuthenticatorAssertionResponse{
|
||||
ClientDataJSON: clientDataJSON,
|
||||
AuthenticatorData: authenticatorData,
|
||||
Signature: signature,
|
||||
UserHandle: userHandle,
|
||||
}
|
||||
|
||||
result, err := client.CompleteAuthentication(ctx, challenge, response, credentialID)
|
||||
return err
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Supported Algorithms
|
||||
|
||||
<Tabs>
|
||||
<Tab title="ES256">ECDSA with P-256 curve and SHA-256</Tab>
|
||||
<Tab title="RS256">RSASSA-PKCS1-v1_5 with SHA-256</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Attestation Formats
|
||||
|
||||
<Callout type="info">
|
||||
1. **none**: No attestation (development/testing) 2. **packed**:
|
||||
Self-attestation or certificate chain 3. **fido-u2f**: Legacy U2F
|
||||
authenticators 4. **android-safetynet**: Android device attestation
|
||||
</Callout>
|
||||
|
||||
### Security Features
|
||||
|
||||
- **Challenge uniqueness**: Each challenge is unique and time-bound
|
||||
- **Origin validation**: Ensures requests come from trusted origins
|
||||
- **User verification**: Requires biometric or PIN when configured
|
||||
- **Counter tracking**: Detects cloned credentials
|
||||
- **Credential isolation**: Each DID has separate credential namespace
|
||||
|
||||
## Configuration
|
||||
|
||||
### Chain Parameters
|
||||
|
||||
<CodeGroup>
|
||||
```json Configuration Example
|
||||
{
|
||||
"webauthn": {
|
||||
"rp_id": "sonr.io",
|
||||
"rp_name": "Sonr Network",
|
||||
"timeout": 60000,
|
||||
"user_verification": "preferred",
|
||||
"attestation": "none",
|
||||
"allowed_origins": [
|
||||
"https://sonr.io",
|
||||
"https://app.sonr.io"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<Accordion title="Common WebAuthn Issues">
|
||||
- **"Invalid attestation format"**: Ensure authenticator supports the
|
||||
configured format - **"Challenge mismatch"**: Verify challenge hasn't expired
|
||||
- **"Origin validation failed"**: Check allowed origins list - **"User
|
||||
verification required"**: Ensure authenticator supports verification
|
||||
</Accordion>
|
||||
|
||||
## Contributing
|
||||
|
||||
### Development Setup
|
||||
|
||||
<CodeGroup>
|
||||
```bash Setup Commands
|
||||
# Clone repository
|
||||
git clone https://github.com/sonr-io/sonr.git
|
||||
|
||||
# Install dependencies
|
||||
|
||||
make install
|
||||
|
||||
# Run WebAuthn tests
|
||||
|
||||
make test-webauthn
|
||||
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## References
|
||||
|
||||
<Card
|
||||
title="WebAuthn Specifications"
|
||||
icon="link"
|
||||
href="https://www.w3.org/TR/webauthn/"
|
||||
>
|
||||
Official W3C WebAuthn Specification
|
||||
</Card>
|
||||
|
||||
<Card
|
||||
title="FIDO2 CTAP"
|
||||
icon="lock"
|
||||
href="https://fidoalliance.org/specs/fido-v2.0/"
|
||||
>
|
||||
FIDO2 Client to Authenticator Protocol
|
||||
</Card>
|
||||
|
||||
## License
|
||||
|
||||
Copyright 2024 Sonr Inc. Licensed under the Apache License, Version 2.0.
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user