Code-First Security: A Practical Implementation of a Go Passkey Manager
Introduction — What are ‘Passkeys’ and why should we use them?
I was asked by a young student asking me about passkeys, why we should use them, so I decided to implement a sample code to make a demonstration.” This simple question highlights a major shift in digital security: we are finally moving away from the era of shared secrets. While passwords require us to memorize complex strings — which we inevitably reuse or forget — passkeys leverage asymmetric cryptography to create a login experience that is both more secure and significantly more convenient.
The core advantage of passkeys lies in their phishing resistance. Because a passkey is tied to a specific domain and never leaves your physical device, a ma…
Code-First Security: A Practical Implementation of a Go Passkey Manager
Introduction — What are ‘Passkeys’ and why should we use them?
I was asked by a young student asking me about passkeys, why we should use them, so I decided to implement a sample code to make a demonstration.” This simple question highlights a major shift in digital security: we are finally moving away from the era of shared secrets. While passwords require us to memorize complex strings — which we inevitably reuse or forget — passkeys leverage asymmetric cryptography to create a login experience that is both more secure and significantly more convenient.
The core advantage of passkeys lies in their phishing resistance. Because a passkey is tied to a specific domain and never leaves your physical device, a malicious website cannot “trick” you into giving up your credentials. Furthermore, passkeys eliminate the risk of server-side data breaches; since the server only stores a public key rather than a password hash, there is no “secret” for a hacker to steal. By replacing manual entry with biometrics like FaceID or TouchID, passkeys offer a seamless “zero-friction” workflow that proves security doesn’t always have to come at the cost of user experience.
Why Passkeys Win: A Quick Comparison
| Feature | Traditional Passwords | Passkeys (WebAuthn) |
| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------ |
| **Authentication Type** | Knowledge (What you know) | Possession + Inherence (What you have + Who you are) |
| **Phishing Protection** | **Low:** Users can be tricked into typing passwords. | **High:** Cryptographically bound to the real website. |
| **Data Breach Risk** | **High:** Stolen hashes can be cracked offline. | **None:** Public keys are useless to an attacker. |
| **User Experience** | **Frustrating:** Requires managers or memory. | **Seamless:** Uses device biometrics or PINs. |
Sample Application to showcase a practical ‘Passkey’ implementation
To transform the abstract theory of FIDO2 into a tangible learning tool, I collaborated with IBM Bob to architect a functional passkey demonstration. The system utilizes a robust Go backend to manage the complex WebAuthn handshake, paired with a clean HTML/JavaScript frontend for a transparent user experience. During my testing, the application generated passkeys seamlessly, which I was able to store securely within my Bitwarden manager — proving that these ‘hardware-backed’ credentials integrate perfectly with modern security workflows. For those looking to dive deeper into the ‘how’ and ‘why,’ Bob has produced comprehensive documentation within the project, including a Quick Start Guide and detailed Architecture Diagrams, ensuring the mechanics are as clear as the implementation itself.
Project Breakdown at a Glance
Based on the project files, here is how the educational application is structured:
passkey-demo/
├── server/ # Go backend server
│ ├── main.go # Server entry point
│ ├── handlers.go # HTTP handlers
│ ├── storage.go # In-memory storage
│ ├── go.mod # Go dependencies
│ └── go.sum # Dependency checksums
├── client/ # HTML/JavaScript client
│ ├── index.html # Main page
│ ├── register.html # Registration page
│ └── login.html # Login page
├── k8s/ # Kubernetes manifests
│ ├── namespace.yaml # Namespace definition
│ ├── configmap.yaml # Configuration
│ ├── deployment.yaml # Deployment spec
│ ├── service.yaml # Service definition
│ ├── ingress.yaml # Ingress rules
│ ├── hpa.yaml # Horizontal Pod Autoscaler
│ └── README.md # K8s deployment guide
├── Dockerfile # Container image definition
├── .dockerignore # Docker ignore rules
├── docker-compose.yml # Docker Compose configuration
├── start.sh # Start script (detached mode)
├── stop.sh # Stop script
├── ARCHITECTURE.md # Architecture diagrams (Mermaid)
├── QUICKSTART.md # Quick start guide
├── SETUP.md # Detailed setup instructions
├── API.md # API documentation
└── PROJECT_OVERVIEW.md # Comprehensive overview
- The Backend (Go): A RESTful API that leverages the go-webauthn library to handle registration and login challenges.
package main
import (
"log"
"net/http"
"os"
"github.com/go-webauthn/webauthn/webauthn"
"github.com/gorilla/mux"
)
func main() {
// Get configuration from environment or use defaults
rpID := getEnv("RP_ID", "localhost")
rpOrigin := getEnv("RP_ORIGIN", "http://localhost:8080")
port := getEnv("PORT", "8080")
// Initialize WebAuthn
wconfig := &webauthn.Config{
RPDisplayName: "Passkey Demo",
RPID: rpID,
RPOrigins: []string{rpOrigin},
// Timeout for registration/authentication (in milliseconds)
Timeouts: webauthn.TimeoutsConfig{
Login: webauthn.TimeoutConfig{
Enforce: true,
Timeout: 60000,
TimeoutUVD: 60000,
},
Registration: webauthn.TimeoutConfig{
Enforce: true,
Timeout: 60000,
TimeoutUVD: 60000,
},
},
}
webAuthn, err := webauthn.New(wconfig)
if err != nil {
log.Fatalf("Failed to create WebAuthn instance: %v", err)
}
// Initialize storage
storage := NewStorage()
// Initialize handlers
handlers := NewHandlers(webAuthn, storage)
// Setup router
r := mux.NewRouter()
// API routes
api := r.PathPrefix("/api").Subrouter()
api.HandleFunc("/register/begin", handlers.RegisterBegin).Methods("POST", "OPTIONS")
api.HandleFunc("/register/finish", handlers.RegisterFinish).Methods("POST", "OPTIONS")
api.HandleFunc("/login/begin", handlers.LoginBegin).Methods("POST", "OPTIONS")
api.HandleFunc("/login/finish", handlers.LoginFinish).Methods("POST", "OPTIONS")
// Health check endpoint
r.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
w.Write([]byte("OK"))
}).Methods("GET")
// Serve static files from client directory
clientDir := "../client"
if _, err := os.Stat(clientDir); err == nil {
r.PathPrefix("/").Handler(http.FileServer(http.Dir(clientDir)))
log.Printf("Serving static files from %s", clientDir)
} else {
log.Printf("Client directory not found at %s, skipping static file serving", clientDir)
}
// Apply middleware
handler := LoggingMiddleware(EnableCORS(r))
// Start server
log.Printf("Starting server on port %s", port)
log.Printf("RP ID: %s", rpID)
log.Printf("RP Origin: %s", rpOrigin)
log.Printf("API endpoints:")
log.Printf(" POST /api/register/begin")
log.Printf(" POST /api/register/finish")
log.Printf(" POST /api/login/begin")
log.Printf(" POST /api/login/finish")
log.Printf(" GET /health")
if err := http.ListenAndServe(":"+port, handler); err != nil {
log.Fatalf("Server failed to start: %v", err)
}
}
// getEnv gets an environment variable or returns a default value
func getEnv(key, defaultValue string) string {
value := os.Getenv(key)
if value == "" {
return defaultValue
}
return value
}
// Made with Bob
- The Frontend (Vanilla JS): Uses the native
navigator.credentialsbrowser API to talk to your biometrics or security keys.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Register - Passkey Demo</title>
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
min-height: 100vh;
display: flex;
justify-content: center;
align-items: center;
padding: 20px;
}
.container {
background: white;
border-radius: 20px;
box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
padding: 40px;
max-width: 500px;
width: 100%;
}
h1 {
color: #333;
margin-bottom: 10px;
text-align: center;
}
.subtitle {
color: #666;
margin-bottom: 30px;
text-align: center;
}
.form-group {
margin-bottom: 20px;
}
label {
display: block;
margin-bottom: 8px;
color: #555;
font-weight: 600;
}
input {
width: 100%;
padding: 12px;
border: 2px solid #e0e0e0;
border-radius: 8px;
font-size: 1em;
transition: border-color 0.3s;
}
input:focus {
outline: none;
border-color: #667eea;
}
.btn {
width: 100%;
padding: 15px;
font-size: 1.1em;
border: none;
border-radius: 10px;
cursor: pointer;
transition: all 0.3s ease;
font-weight: 600;
margin-top: 10px;
}
.btn-primary {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
}
.btn-primary:hover:not(:disabled) {
transform: translateY(-2px);
box-shadow: 0 10px 20px rgba(102, 126, 234, 0.4);
}
.btn-primary:disabled {
opacity: 0.6;
cursor: not-allowed;
}
.btn-secondary {
background: white;
color: #667eea;
border: 2px solid #667eea;
}
.btn-secondary:hover {
background: #f5f5f5;
}
.message {
padding: 15px;
border-radius: 8px;
margin-bottom: 20px;
display: none;
}
.message.success {
background: #d4edda;
color: #155724;
border: 1px solid #c3e6cb;
}
.message.error {
background: #f8d7da;
color: #721c24;
border: 1px solid #f5c6cb;
}
.message.info {
background: #d1ecf1;
color: #0c5460;
border: 1px solid #bee5eb;
}
.back-link {
text-align: center;
margin-top: 20px;
}
.back-link a {
color: #667eea;
text-decoration: none;
}
.back-link a:hover {
text-decoration: underline;
}
.loading {
display: none;
text-align: center;
margin: 20px 0;
}
.spinner {
border: 3px solid #f3f3f3;
border-top: 3px solid #667eea;
border-radius: 50%;
width: 40px;
height: 40px;
animation: spin 1s linear infinite;
margin: 0 auto;
}
@keyframes spin {
0% { transform: rotate(0deg); }
100% { transform: rotate(360deg); }
}
.info-box {
background: #e3f2fd;
border-left: 4px solid #2196f3;
padding: 15px;
margin-bottom: 20px;
border-radius: 5px;
font-size: 0.9em;
}
</style>
</head>
<body>
<div class="container">
<h1>🔐 Register</h1>
<p class="subtitle">Create a new account with a passkey</p>
<div id="message" class="message"></div>
<div class="info-box">
<strong>How it works:</strong> Enter your username and click register. You'll be prompted to create a passkey using your device's biometric sensor, security key, or PIN.
</div>
<form id="registerForm">
<div class="form-group">
<label for="username">Username or Email</label>
<input
type="text"
id="username"
name="username"
placeholder="Enter your username or email"
required
autocomplete="username webauthn"
>
</div>
<button type="submit" class="btn btn-primary" id="registerBtn">
Register with Passkey
</button>
</form>
<div class="loading" id="loading">
<div class="spinner"></div>
<p style="margin-top: 10px; color: #666;">Creating your passkey...</p>
</div>
<div class="back-link">
<a href="index.html">← Back to Home</a>
</div>
</div>
<script>
const API_BASE = 'http://localhost:8080/api';
// Helper function to show messages
function showMessage(text, type) {
const messageEl = document.getElementById('message');
messageEl.textContent = text;
messageEl.className = `message ${type}`;
messageEl.style.display = 'block';
}
// Helper function to hide messages
function hideMessage() {
document.getElementById('message').style.display = 'none';
}
// Helper function to show/hide loading
function setLoading(isLoading) {
document.getElementById('loading').style.display = isLoading ? 'block' : 'none';
document.getElementById('registerBtn').disabled = isLoading;
document.getElementById('registerForm').style.display = isLoading ? 'none' : 'block';
}
// Convert base64url to ArrayBuffer
function base64urlToBuffer(base64url) {
const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
const padLen = (4 - (base64.length % 4)) % 4;
const padded = base64 + '='.repeat(padLen);
const binary = atob(padded);
const bytes = new Uint8Array(binary.length);
for (let i = 0; i < binary.length; i++) {
bytes[i] = binary.charCodeAt(i);
}
return bytes.buffer;
}
// Convert ArrayBuffer to base64url
function bufferToBase64url(buffer) {
const bytes = new Uint8Array(buffer);
let binary = '';
for (let i = 0; i < bytes.length; i++) {
binary += String.fromCharCode(bytes[i]);
}
const base64 = btoa(binary);
return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
}
// Handle registration form submission
document.getElementById('registerForm').addEventListener('submit', async (e) => {
e.preventDefault();
hideMessage();
const username = document.getElementById('username').value.trim();
if (!username) {
showMessage('Please enter a username', 'error');
return;
}
try {
setLoading(true);
// Step 1: Begin registration
const beginResponse = await fetch(`${API_BASE}/register/begin`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username })
});
if (!beginResponse.ok) {
const error = await beginResponse.text();
throw new Error(error || 'Failed to begin registration');
}
const options = await beginResponse.json();
console.log('Registration options:', options);
// Convert base64url strings to ArrayBuffers
options.publicKey.challenge = base64urlToBuffer(options.publicKey.challenge);
options.publicKey.user.id = base64urlToBuffer(options.publicKey.user.id);
if (options.publicKey.excludeCredentials) {
options.publicKey.excludeCredentials = options.publicKey.excludeCredentials.map(cred => ({
...cred,
id: base64urlToBuffer(cred.id)
}));
}
// Step 2: Create credential
showMessage('Please follow your device prompts to create a passkey...', 'info');
const credential = await navigator.credentials.create(options);
console.log('Credential created:', credential);
// Step 3: Finish registration
const credentialJSON = {
id: credential.id,
rawId: bufferToBase64url(credential.rawId),
type: credential.type,
response: {
attestationObject: bufferToBase64url(credential.response.attestationObject),
clientDataJSON: bufferToBase64url(credential.response.clientDataJSON)
}
};
const finishResponse = await fetch(`${API_BASE}/register/finish?username=${encodeURIComponent(username)}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(credentialJSON)
});
if (!finishResponse.ok) {
const error = await finishResponse.text();
throw new Error(error || 'Failed to complete registration');
}
const result = await finishResponse.json();
console.log('Registration result:', result);
showMessage('Registration successful! Redirecting to login...', 'success');
setTimeout(() => {
window.location.href = 'login.html';
}, 2000);
} catch (error) {
console.error('Registration error:', error);
showMessage(`Registration failed: ${error.message}`, 'error');
setLoading(false);
}
});
// Check WebAuthn support
if (!window.PublicKeyCredential) {
showMessage('WebAuthn is not supported in this browser. Please use a modern browser.', 'error');
document.getElementById('registerBtn').disabled = true;
}
</script>
</body>
</html>
-
Storage Strategy: Currently uses in-memory storage for simplicity, making it a perfect “sandbox” for students to experiment without database overhead.
-
Deployment Versatility: Bob has configured the app to run via a simple script (
start.sh), Docker, or even Kubernetes for more advanced learners.
# Multi-stage build for smaller final image
FROM golang:1.21-alpine AS builder
# Install build dependencies
RUN apk add --no-cache git ca-certificates tzdata
# Set working directory
WORKDIR /build
# Copy go mod files
COPY server/go.mod server/go.sum ./
# Download dependencies
RUN go mod download
# Copy source code
COPY server/ ./
# Build the application
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o passkey-demo .
# Final stage - minimal image
FROM alpine:latest
# Install ca-certificates for HTTPS
RUN apk --no-cache add ca-certificates tzdata
# Create non-root user
RUN addgroup -g 1000 appuser && \
adduser -D -u 1000 -G appuser appuser
# Set working directory
WORKDIR /app
# Copy binary from builder
COPY --from=builder /build/passkey-demo .
# Copy client files
COPY client/ ./client/
# Change ownership to non-root user
RUN chown -R appuser:appuser /app
# Switch to non-root user
USER appuser
# Expose port
EXPOSE 8080
# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1
# Set environment variables
ENV RP_ID=localhost \
RP_ORIGIN=http://localhost:8080 \
PORT=8080
# Run the application
CMD ["./passkey-demo"]
apiVersion: apps/v1
kind: Deployment
metadata:
name: passkey-demo
namespace: passkey-demo
labels:
app: passkey-demo
spec:
replicas: 3
selector:
matchLabels:
app: passkey-demo
template:
metadata:
labels:
app: passkey-demo
spec:
containers:
- name: passkey-demo
image: passkey-demo:latest
imagePullPolicy: IfNotPresent
ports:
- containerPort: 8080
name: http
protocol: TCP
env:
- name: RP_ID
valueFrom:
configMapKeyRef:
name: passkey-demo-config
key: RP_ID
- name: RP_ORIGIN
valueFrom:
configMapKeyRef:
name: passkey-demo-config
key: RP_ORIGIN
- name: PORT
valueFrom:
configMapKeyRef:
name: passkey-demo-config
key: PORT
resources:
requests:
memory: "64Mi"
cpu: "100m"
limits:
memory: "128Mi"
cpu: "200m"
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 10
periodSeconds: 30
timeoutSeconds: 3
failureThreshold: 3
readinessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 5
periodSeconds: 10
timeoutSeconds: 3
failureThreshold: 3
securityContext:
runAsNonRoot: true
runAsUser: 1000
allowPrivilegeEscalation: false
readOnlyRootFilesystem: false
capabilities:
drop:
- ALL
# Made with Bob
Understanding the “Bitwarden” Connection
When you store a passkey in Bitwarden during this demo, you are witnessing cross-platform passkey support. The Go server sends a challenge, and instead of your laptop’s local chip (TPM) answering, your Bitwarden browser extension intercepts the request, signs it, and saves the private key.
Conclusion
In conclusion, the fundamental principle of passkeys represents a paradigm shift from “something you know” to “something you have” and “something you are,” replacing vulnerable shared secrets with robust asymmetric cryptography. This demonstration application successfully showcases the efficiency of this transition by distilling a complex security protocol into a frictionless, one-touch experience. By removing the burden of password creation and management while simultaneously neutralizing the threat of phishing and server-side breaches, the project proves that high-level security does not have to compromise user convenience. As users seamlessly generate and store these credentials in tools like Bitwarden, it becomes clear that passkeys are not just a theoretical improvement, but a practical, ready-to-use standard for a more secure digital future.
>>> Thanks for reading 🔐 <<<
Links
- Repository of this demonstration: https://github.com/aairom?tab=repositories
- Web authentication explananation: https://webauthn.guide/
- Fido alliance: https://fidoalliance.org/
- Go Webauthnetication Library used: https://github.com/go-webauthn/webauthn