# Vaultwarden SSO Feature Status and Configuration

**Document Date:** December 21, 2025  
**Last Updated:** December 21, 2025  
**Status:** SSO Configured, Waiting for Stable Release

---

## Executive Summary

Vaultwarden has been successfully deployed with **SSO integration pre-configured** for Authentik. However, SSO functionality is currently **only available in testing images** and not yet in the stable release. This document explains the current state, our decision to wait for stable, and how to activate SSO when it becomes available.

## Current Deployment Status

### What's Working
- ✅ Vaultwarden deployed successfully at `https://vault.jnss.me`
- ✅ PostgreSQL backend via Unix socket
- ✅ Admin panel accessible and working
- ✅ Email/password authentication working
- ✅ SMTP notifications configured
- ✅ All SSO environment variables correctly configured
- ✅ Authentik OAuth2 provider created and ready

### What's Not Working (By Design)
- ❌ SSO login option not appearing on login page
- ❌ "Use single sign-on" button missing

**Reason:** Using stable image (`vaultwarden/server:latest` v1.34.3) which does not include SSO code.

## Investigation Summary (Dec 21, 2025)

### Problem Reported
User deployed Vaultwarden with `vaultwarden_sso_enabled: true` and configured Authentik integration following official guides, but no SSO option appeared on the login page.

### Root Cause Identified
After investigation including:
- Service status check (healthy, running normally)
- Environment variable verification (all SSO vars present and correct)
- Configuration review (matches Authentik integration guide perfectly)
- API endpoint inspection (`/api/config` returns `"sso":""`)
- Official documentation review

**Finding:** SSO feature is only compiled into `vaultwarden/server:testing` images, not stable releases.

### Evidence

From [Vaultwarden Official Wiki](https://github.com/dani-garcia/vaultwarden/wiki):

> **Testing features**
> 
> Features available in the `testing` docker image:
> - Single Sign-On (SSO), see [Documentation](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-SSO-support-using-OpenId-Connect)

From [SSO Documentation Page](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-SSO-support-using-OpenId-Connect):

> ⚠️ **Important**
> 
> ‼️ ‼️ ‼️  
> SSO is currently only available in the `:testing` tagged images!  
> The current stable `v1.34.3` **does not** contain the SSO feature.  
> ‼️ ‼️ ‼️

### API Response Analysis

```bash
# API config endpoint shows SSO not available
curl -s http://127.0.0.1:8080/api/config | grep -o '"sso":"[^"]*"'
# Returns: "sso":""  ← Empty = feature not compiled in

# Environment variables are set correctly
podman exec vaultwarden env | grep -i sso
SSO_ENABLED=true
SSO_ONLY=false
SSO_CLIENT_ID=DDOQXdwFn6pi4FtSvo7PK5b63pRzyD552xapTZGr
SSO_CLIENT_SECRET=02D308Sle2w2NPsi7UaXb3bvKKK4punFDT2LiVqKpzvEFqgPpyLysA8Z5yS4g8t4LYmsI9txLE02l5MtWP5R2RBavLhYHjNFHcwEmvYB94bOJw45YmgiGePaW4NHKcfY
SSO_AUTHORITY=https://auth.jnss.me/application/o/vaultwarden/
SSO_SCOPES="openid email profile offline_access"
# ... etc (all correct)
```

**Conclusion:** Environment configured correctly, feature simply not available in stable release.

## Decision: Wait for Stable Release

### Rationale

**Why NOT switch to testing image:**
1. **Production stability** - This is a password manager handling sensitive credentials
2. **Testing images are volatile** - Frequent updates, potential bugs
3. **No ETA for stable** - SSO marked as "testing feature" indefinitely
4. **Current auth works fine** - Email/password login is secure and functional
5. **Configuration is ready** - When SSO reaches stable, it will work immediately

**Why keep SSO configured:**
1. **Future-ready** - No additional work needed when SSO stabilizes
2. **No harm** - Environment variables are ignored by stable image
3. **Documentation** - Clear record of SSO setup for future reference
4. **Authentik provider ready** - Already created and configured

### Alternatives Considered

| Option | Pros | Cons | Decision |
|--------|------|------|----------|
| Use `testing` image | SSO available now | Unstable, potential data loss, frequent breaking changes | ❌ Rejected |
| Wait for stable | Stable, reliable, secure | No SSO until unknown future date | ✅ **Selected** |
| Remove SSO config | Cleaner config | Requires reconfiguration later | ❌ Rejected |
| Dual deployment | Test SSO separately | Resource waste, complexity | ❌ Rejected |

## Current Configuration

### Ansible Role Variables

Location: `roles/vaultwarden/defaults/main.yml`

```yaml
# Container version (stable, no SSO)
vaultwarden_version: "latest"

# SSO enabled (ready for when feature reaches stable)
vaultwarden_sso_enabled: true
vaultwarden_sso_only: false
vaultwarden_sso_client_id: "{{ vault_vaultwarden_sso_client_id }}"
vaultwarden_sso_client_secret: "{{ vault_vaultwarden_sso_client_secret }}"
vaultwarden_sso_authority: "https://auth.jnss.me/application/o/vaultwarden/"
vaultwarden_sso_scopes: "openid email profile offline_access"
vaultwarden_sso_signups_match_email: true
vaultwarden_sso_allow_unknown_email_verification: false
vaultwarden_sso_client_cache_expiration: 0
```

### Vault Variables (Encrypted)

Location: `group_vars/homelab/vault.yml`

```yaml
# SSO credentials from Authentik
vault_vaultwarden_sso_client_id: "DDOQXdwFn6pi4FtSvo7PK5b63pRzyD552xapTZGr"
vault_vaultwarden_sso_client_secret: "02D308Sle2w2NPsi7UaXb3bvKKK4punFDT2LiVqKpzvEFqgPpyLysA8Z5yS4g8t4LYmsI9txLE02l5MtWP5R2RBavLhYHjNFHcwEmvYB94bOJw45YmgiGePaW4NHKcfY"
```

### Authentik Provider Configuration

**Provider Details:**
- **Name:** Vaultwarden
- **Type:** OAuth2/OpenID Connect Provider
- **Client Type:** Confidential
- **Client ID:** `DDOQXdwFn6pi4FtSvo7PK5b63pRzyD552xapTZGr`
- **Application Slug:** `vaultwarden`
- **Redirect URI:** `https://vault.jnss.me/identity/connect/oidc-signin`

**Scopes Configured:**
- ✅ `authentik default OAuth Mapping: OpenID 'openid'`
- ✅ `authentik default OAuth Mapping: OpenID 'email'`
- ✅ `authentik default OAuth Mapping: OpenID 'profile'`
- ✅ `authentik default OAuth Mapping: OpenID 'offline_access'`

**Token Settings:**
- Access token validity: > 5 minutes
- Refresh token enabled via `offline_access` scope

**Authority URL:** `https://auth.jnss.me/application/o/vaultwarden/`

### Deployed Environment (VPS)

```bash
# Deployed environment file
Location: /opt/vaultwarden/.env

# All SSO variables present and correct
SSO_ENABLED=true
SSO_AUTHORITY=https://auth.jnss.me/application/o/vaultwarden/
SSO_SCOPES="openid email profile offline_access"
# ... etc
```

## How to Activate SSO (Future)

When Vaultwarden SSO reaches stable release:

### Automatic Activation (Recommended)

1. **Monitor Vaultwarden releases** for SSO in stable:
   - Watch: https://github.com/dani-garcia/vaultwarden/releases
   - Look for: SSO feature in stable image changelog

2. **Update container** (standard maintenance):
   ```bash
   ansible-playbook rick-infra.yml --tags vaultwarden --ask-vault-pass
   ```

3. **Verify SSO is available**:
   ```bash
   ssh root@69.62.119.31 "curl -s http://127.0.0.1:8080/api/config | grep sso"
   # Should return: "sso":"https://vault.jnss.me" or similar
   ```

4. **Test SSO**:
   - Navigate to: https://vault.jnss.me
   - Log out if logged in
   - Enter verified email address
   - Click "Use single sign-on" button
   - Should redirect to Authentik login

**No configuration changes needed** - Everything is already set up correctly.

### Manual Testing (Use Testing Image)

If you want to test SSO before stable release:

1. **Backup current deployment**:
   ```bash
   ansible-playbook playbooks/backup-vaultwarden.yml  # Create if needed
   ```

2. **Change to testing image** in `roles/vaultwarden/defaults/main.yml`:
   ```yaml
   vaultwarden_version: "testing"
   ```

3. **Deploy**:
   ```bash
   ansible-playbook rick-infra.yml --tags vaultwarden --ask-vault-pass
   ```

4. **Test SSO** (same as above)

5. **Revert to stable** when testing complete:
   ```yaml
   vaultwarden_version: "latest"
   ```

**Warning:** Testing images may contain bugs, data corruption risks, or breaking changes. Not recommended for production password manager.

## Verification Commands

### Check Current Image Version
```bash
ssh root@69.62.119.31 "podman inspect vaultwarden --format '{{.ImageName}}'"
# Expected: docker.io/vaultwarden/server:latest
```

### Check SSO API Status
```bash
ssh root@69.62.119.31 "curl -s http://127.0.0.1:8080/api/config | grep -o '\"sso\":\"[^\"]*\"'"
# Current: "sso":""  (empty = not available)
# Future:  "sso":"https://vault.jnss.me"  (URL = available)
```

### Check SSO Environment Variables
```bash
ssh root@69.62.119.31 "podman exec vaultwarden env | grep -i sso | sort"
# Should show all SSO_* variables configured correctly
```

### Check Vaultwarden Version
```bash
ssh root@69.62.119.31 "podman exec vaultwarden /vaultwarden --version"
# Current: Vaultwarden 1.34.3
```

## Documentation Updates

The following files have been updated to document this finding:

1. **`roles/vaultwarden/README.md`**
   - Added warning banner in SSO configuration section
   - Updated troubleshooting section with SSO status checks
   - Documented stable vs testing image behavior

2. **`roles/vaultwarden/VAULT_VARIABLES.md`**
   - Added SSO feature status warning
   - Documented that credentials are ready but inactive

3. **`roles/vaultwarden/defaults/main.yml`**
   - Added comments explaining SSO availability

4. **`docs/vaultwarden-sso-status.md`** (this document)
   - Complete investigation findings
   - Configuration reference
   - Activation procedures

## Timeline

- **2025-07-30:** Vaultwarden v1.34.3 released (current stable)
- **2025-12-21:** Vaultwarden deployed with SSO pre-configured
- **2025-12-21:** Investigation completed, SSO status documented
- **TBD:** SSO feature reaches stable release (no ETA)
- **Future:** Automatic SSO activation on next deployment

## Related Documentation

- [Vaultwarden Official Wiki](https://github.com/dani-garcia/vaultwarden/wiki)
- [SSO Documentation](https://github.com/dani-garcia/vaultwarden/wiki/Enabling-SSO-support-using-OpenId-Connect)
- [Authentik Integration Guide](https://integrations.goauthentik.io/security/vaultwarden/)
- [Vaultwarden Testing Features](https://github.com/dani-garcia/vaultwarden/wiki#testing-features)

## Contact

For questions about this deployment:
- Infrastructure repo: `/home/fitz/rick-infra`
- Role location: `roles/vaultwarden/`
- Service: `vault.jnss.me`
- Host: `arch-vps` (69.62.119.31)

---

**Status:** SSO configured and ready, waiting for upstream stable release. No action required.