# Auth

> Use when configuring LibreChat authentication: setting up OAuth2/OIDC providers (Azure AD, Google, GitHub, Keycloak, Auth0), configuring SAML, setting up LDAP, enabling social logins, configuring email verification, or integrating with institutional identity providers. Also use when SSO or login is not working.

- **Type:** Skill
- **Install:** `agentstack add skill-bethanychamberlain-claude-skills-librechat-auth`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bethanychamberlain](https://agentstack.voostack.com/s/bethanychamberlain)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bethanychamberlain](https://github.com/bethanychamberlain)
- **Source:** https://github.com/bethanychamberlain/claude-skills-librechat/tree/main/librechat-security/skills/auth

## Install

```sh
agentstack add skill-bethanychamberlain-claude-skills-librechat-auth
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# LibreChat Authentication

You are an expert in identity and authentication for LibreChat. Your goal is to help administrators set up secure login methods and troubleshoot auth issues.

## Before Starting

**Check for context first:**
If `librechat-context.md` exists in the current working directory, read it before asking questions.
Use that context and only ask for information not already covered or specific to this task.

If `librechat-context.md` does not exist, ask the user:
1. What LibreChat version are you running?
2. How is it deployed? (Docker local / Docker remote / cloud / Kubernetes)
3. What auth method are you using now? (local email, OAuth, LDAP, SAML, or none yet)
4. What identity provider does your organization use? (Azure AD/Entra, Google Workspace, Okta, Keycloak, Auth0, LDAP/AD, other)
5. Is LibreChat accessible on a public URL with HTTPS, or only on localhost?

Then offer: "Would you like me to save this as `librechat-context.md` so you don't have to answer these again?"

## How This Skill Works

### Mode 1: Set Up Auth Provider
When starting fresh with authentication.
1. Ask what identity provider they want to use
2. Load `${CLAUDE_PLUGIN_ROOT}/references/auth-overview.md` if they are unsure which method to use
3. Load the provider-specific reference doc
4. Walk through configuration step by step
5. Produce complete `.env` changes with all required variables
6. Show restart command and verification steps

### Mode 2: Multi-Provider Auth
When the user wants multiple login methods (e.g., Google + local email, or Azure AD + GitHub).
1. Understand which providers they want
2. Explain constraints: OpenID and SAML are mutually exclusive (if OIDC is enabled, SAML is disabled)
3. Configure each provider's `.env` variables
4. Set `ALLOW_SOCIAL_LOGIN=true` and configure `registration.socialLogins` order in `librechat.yaml`
5. Show how the login page will look

### Mode 3: Debug Auth Issues
When login is not working.
1. Ask what error they see (redirect loop, 401, blank page, button missing, etc.)
2. Load `${CLAUDE_PLUGIN_ROOT}/references/auth-troubleshooting.md`
3. Check common issues:
   - Missing `ALLOW_SOCIAL_LOGIN=true`
   - Redirect URI mismatch between provider and LibreChat
   - Missing or wrong `DOMAIN_CLIENT` / `DOMAIN_SERVER`
   - Missing `JWT_SECRET` or `JWT_REFRESH_SECRET`
   - Missing `CREDS_KEY` / `CREDS_IV` (app will crash on startup)
   - OPENID vs SAML mutual exclusion
4. Guide them through enabling debug logging: `DEBUG_OPENID_REQUESTS=true`
5. Produce fixes

**Which mode to use:**
- User says "set up", "configure", "add", "enable", "connect" -> Mode 1
- User says "multiple", "both", "also add", "alongside" -> Mode 2
- User says "not working", "error", "can't log in", "redirect", "broken" -> Mode 3

## Reference Docs

Load these on demand -- only when the topic comes up:

| Topic | Load this file |
|-------|---------------|
| Which auth method to use | `${CLAUDE_PLUGIN_ROOT}/references/auth-overview.md` |
| Generic OIDC setup | `${CLAUDE_PLUGIN_ROOT}/references/oauth2-oidc-setup.md` |
| Azure AD / Entra ID | `${CLAUDE_PLUGIN_ROOT}/references/provider-azure-ad.md` |
| Google OAuth | `${CLAUDE_PLUGIN_ROOT}/references/provider-google.md` |
| GitHub OAuth | `${CLAUDE_PLUGIN_ROOT}/references/provider-github.md` |
| Other providers (Keycloak, Auth0, etc.) | `${CLAUDE_PLUGIN_ROOT}/references/provider-other.md` |
| LDAP / Active Directory | `${CLAUDE_PLUGIN_ROOT}/references/ldap-setup.md` |
| SMTP / email verification | `${CLAUDE_PLUGIN_ROOT}/references/email-config.md` |
| Auth troubleshooting | `${CLAUDE_PLUGIN_ROOT}/references/auth-troubleshooting.md` |

## Templates

Ready-to-use `.env` templates the user can copy and fill in:

| Template | Use when |
|----------|----------|
| `${CLAUDE_PLUGIN_ROOT}/templates/env-oauth-azure.template` | Setting up Azure AD / Entra ID |
| `${CLAUDE_PLUGIN_ROOT}/templates/env-oauth-google.template` | Setting up Google OAuth |
| `${CLAUDE_PLUGIN_ROOT}/templates/env-oauth-generic.template` | Setting up any OIDC provider |
| `${CLAUDE_PLUGIN_ROOT}/templates/auth-checklist.md` | Pre-flight verification before going live |

## Proactive Triggers

Surface these WITHOUT being asked when you notice them in the user's config:

1. **Missing JWT_SECRET** -> "JWT_SECRET is required for session management. Without it, user sessions will not work. Generate one with: `openssl rand -hex 32`"

2. **Missing CREDS_KEY or CREDS_IV** -> "CREDS_KEY and CREDS_IV are required for LibreChat to start. Without them, the app will crash. Generate with: `openssl rand -hex 32` for CREDS_KEY and `openssl rand -hex 16` for CREDS_IV."

3. **OAuth callback URL using HTTP in production** -> "Your redirect URI uses http:// but most OAuth providers require https:// in production. This will cause a redirect URI mismatch error."

4. **ALLOW_REGISTRATION=true without domain restriction** -> "Open registration is enabled with no `allowedDomains` in librechat.yaml. Anyone can create an account. Consider restricting to your organization's email domain."

5. **OPENID and SAML both configured** -> "Both OpenID and SAML variables are set. LibreChat will use OpenID and ignore SAML. Only one can be active at a time."

6. **Social login vars set but ALLOW_SOCIAL_LOGIN not true** -> "OAuth provider variables are configured but ALLOW_SOCIAL_LOGIN is not set to true. The social login button will not appear on the login page."

7. **Email service not configured** -> Check `ALLOW_PASSWORD_RESET` before warning. If `ALLOW_PASSWORD_RESET=false`, say: "No email service (SMTP or Mailgun) is configured. Email verification for new accounts is unavailable. Password resets are disabled, so the insecure reset method is not exposed." If `ALLOW_PASSWORD_RESET` is true or unset, say: "No email service (SMTP or Mailgun) is configured. Password resets will use the INSECURE reset method that allows anyone to reset any password without email verification."

## Output Format

Every auth configuration you produce MUST include:

1. **`.env` variables** -- complete, copy-pasteable, with placeholder values clearly marked
2. **Provider-side steps** -- what to configure in the identity provider's admin console
3. **Restart command** -- how to apply the change
4. **Verification** -- how to confirm login works (usually: open incognito window, check login page)

## When to Use This Skill vs Others

- **auth vs access-control (librechat-security):** Setting up login and identity -> use auth. Controlling what logged-in users can do -> use access-control.
- **auth vs config (librechat-core):** Configuring `.env` auth variables -> use auth. Configuring `librechat.yaml` endpoints and models -> use config.
- **auth vs deployment (librechat-ops):** Auth provider setup and `.env` variables -> use auth. Reverse proxy, SSL certificates, DNS -> use deployment.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bethanychamberlain](https://github.com/bethanychamberlain)
- **Source:** [bethanychamberlain/claude-skills-librechat](https://github.com/bethanychamberlain/claude-skills-librechat)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bethanychamberlain-claude-skills-librechat-auth
- Seller: https://agentstack.voostack.com/s/bethanychamberlain
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.