Authentication
- Token
Use an existing identity provider.
- Credentials
Use LDAP sign-in or a configured local account.
- Access rules
Decide what each signed-in client may do.
You can select a sign-in method and verify that permitted requests succeed and other requests are denied.
You decide: Start with the credentials your clients already support; configure only the matching method.
Time: Duration varies: configure and test one method; waiting depends on identity-provider or directory access.
Next: Production checks
Choose a method that matches your clients, then configure and test it. The authentication reference contains the full setting catalog.
Choose a sign-in method
Section titled “Choose a sign-in method”| Your client… | Use | Why |
|---|---|---|
| Already has a JWT from your IdP | Bearer | Fastest — no network calls per request |
| Sends username/password, needs OAuth claims | ROPC | Trades credentials for JWT, gets roles/scopes from IdP |
| Sends username/password, no IdP available | LDAP | Direct validation against directory |
| Repeatedly uses one technical account | Local | Validates configured credentials without a backend authentication request |
Use Bearer tokens unless clients can’t obtain tokens themselves.
Enable bearer-token authentication
Section titled “Enable bearer-token authentication”Two environment variables enable authentication with Bearer tokens:
SCRIBE_AUTH_ENABLED=trueSCRIBE_AUTH_ISSUER=https://auth.example.com/realms/mycompanyOr in HOCON with named providers:
auth { enabled = true providers { default { issuer = "https://auth.example.com/realms/mycompany" audiences = ["scribe"] } }}How methods are selected, including MCP sign-in
How authentication works
Section titled “How authentication works”Clients authenticate by sending an HTTP Authorization header. Scribe supports two header schemes:
| Scheme | Header format | What Scribe receives |
|---|---|---|
| Bearer | Authorization: Bearer <jwt> | A pre-obtained JWT token |
| Basic | Authorization: Basic <base64> | Username and password (base64-encoded) |
The authentication method determines how Scribe validates what it receives:
| Method | Header | Validation |
|---|---|---|
| Bearer tokens | Bearer | Verify JWT signature via JWKS, check claims |
| ROPC | Basic | Exchange credentials with IdP for JWT, then verify |
| LDAP bind | Basic | Search for user DN, bind to LDAP to verify password |
| Local account | Basic | Compare with a configured account; no backend bind |
Scribe tries the configured Basic methods in order, but a matching local account decides alone:
MCP channel
Section titled “MCP channel”The MCP channel uses the same auth: OAuth Bearer first, with configured Basic methods (ROPC, LDAP bind, or local account) when tokens are unavailable. See MCP Channel — Authentication for client-specific setup and MCP Cursor callback issues when OAuth callbacks fail.
Authentication methods
Section titled “Authentication methods”Bearer tokens (recommended)
Section titled “Bearer tokens (recommended)”Clients obtain a JWT from your identity provider and include it in requests:
GET /api/entries/users HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1...- Client authenticates with IdP (browser redirect, client credentials, etc.)
- IdP issues a signed JWT
- Client sends JWT to Scribe in the Authorization header
- Scribe verifies signature against IdP’s public keys (cached from JWKS)
- Scribe checks expiration, audience, and issuer claims
No per-request calls to the IdP. After the initial JWKS fetch, validation happens locally.
ROPC (Resource Owner Password Credentials)
ROPC (Resource Owner Password Credentials)
Section titled “ROPC (Resource Owner Password Credentials)”Clients send username and password via HTTP Basic auth. Scribe exchanges those credentials with your IdP for a JWT, then validates the token.
GET /api/entries/users HTTP/1.1Authorization: Basic YWxpY2U6c2VjcmV0Configuration:
auth { enabled = true methods = [bearer, ropc]
providers { default { issuer = "https://auth.example.com" audiences = ["scribe"] client-id = "scribe" client-secret = ${SCRIBE_AUTH_CLIENT_SECRET} } }
ropc { scopes = "openid profile email" }}LDAP bind
LDAP bind
Section titled “LDAP bind”Clients send username and password via HTTP Basic auth. Scribe searches for the user’s DN, then binds to LDAP with the provided password.
GET /api/entries/users HTTP/1.1Authorization: Basic YWxpY2U6c2VjcmV0No IdP required. Authentication happens directly against your LDAP directory. LDAP-only auth does not require OIDC provider credentials — you do not need to configure auth.providers, issuer, client-id, or client-secret.
Configuration:
auth { enabled = true methods = [ldap]
ldap { base = "ou=users,dc=example,dc=com" bind-attribute = "uid" filter = "(objectClass=person)" }}LDAP connection settings (server URL, bind-dn, bind-password) are inherited from the root ldap {} configuration. Configure a service account there — Scribe uses it to search for user DNs before validating passwords. See the auth reference for pattern-based lookup, LDAP role mapping, and attribute configuration.
auth.ldap.filter decides which entries may authenticate with the ldap auth method. Keep it broad enough for every LDAP account that must reach Scribe, including service accounts that bind to the LDAP channel. Use role mapping and access rules for operator UI or admin access.
Map an LDAP group to the admin role and restrict Observe:
auth.ldap { filter = "(objectClass=person)"
roles { from = memberOf rules = [ { match = "cn=scribe-admins,ou=groups,dc=example,dc=com", format = "admin" } ] }}
monitoring.observe.auth.rules = [ { id = "observe-admins", action = allow, where = "subject.roles = admin" } { id = "deny-rest", action = deny }]Observe write actions and Full diagnostic report export already require the admin role by default. Set monitoring.observe.write.auth.rules only when writes need a different operator role.
When the directory stops answering:
Every LDAP sign-in that needs the directory waits at most auth.ldap.request-timeout (10 seconds by default). Failures count when the directory is unreachable, timed out, or had no free connection; a wrong password counts as an answer, and a sign-in that fails because of what the client sent, such as credentials larger than the directory accepts, never makes other sign-ins fail fast. The login page shows “Sign-in temporarily unavailable” while sign-ins fail fast. Recovery needs no restart, and readiness stays green. Sign-ins that fail immediately are counted, not logged one by one, so clients that retry do not flood the log. The auth.ldap.upstream doctor check and the scribe_ldap_upstream_state gauge show the directory state; see Directory not answering sign-ins.
auth.ldap.breaker { threshold = 5 # failed sign-in checks in a row open-duration = 10s # how long sign-ins fail fast before the next check # enabled = false # let every sign-in wait for the directory instead}Local accounts
Local accounts
Section titled “Local accounts”Local accounts are for fixed technical identities that Scribe should validate from trusted configuration. Authentication accepts the configured DN and, when set, its explicit username alias. The DN is also accepted when it is written with numeric attribute types instead of names, such as 2.5.4.3=scribe,dc=example,dc=com for cn=scribe,dc=example,dc=com. The alias is not derived from the DN, and the configured DN does not need to exist in the backend directory.
auth { enabled = true methods = [local]
local.accounts = [{ bind-dn = "cn=scribe,dc=example,dc=com" bind-password = ${SCRIBE_LOCAL_PASSWORD} username = "scribe" delegation { enabled = true # Optional complete backend override. Without it, Scribe uses the # root ldap.bind-dn and ldap.bind-password pair. bind-dn = "cn=backend-reader,dc=example,dc=com" bind-password = ${SCRIBE_BACKEND_PASSWORD} } }]}delegation.enabled defaults to true. Set it to false when the account may authenticate and use local operations but must not forward an operation to backend LDAP. A local bind, successful login, and LDAP Who-Am-I response do not open a backend connection. Forwarded operations still pass Scribe access rules first and use the selected configured backend identity; the submitted local login password is never forwarded implicitly. A local account has no automatic roles or administrative access.
In every mixed method list, local must be first:
auth.methods = [local, ldap]Browser login follows auth.methods:
auth.methods | The login form accepts |
|---|---|
[local] | Configured local accounts |
[ldap] | LDAP accounts |
[local, ldap] | Both, through the same form |
auth { enabled = true methods = [local, ldap]
ldap.base = "ou=people,dc=example,dc=com" local.accounts = [{ bind-dn = "cn=scribe,dc=example,dc=com" bind-password = ${SCRIBE_LOCAL_PASSWORD} username = "scribe" }]}Adding a local technical account next to ldap therefore keeps browser login available to your LDAP users. A configured local DN or alias takes precedence over an LDAP user with the same name, so choose aliases that do not collide with directory usernames. To restrict browser login to one method, set auth.session.method explicitly, for example auth.session.method = ldap to keep technical accounts out of the browser; the form then treats every submitted name as an LDAP account. Bearer (OIDC) and ROPC are used for browser login only when first in auth.methods or when set as auth.session.method.
Failed local credentials, including an incorrect password for a matching account, use auth.failure-delay before the response. Local credentials are not cached. Account and delegation changes take effect after a process restart. A restart clears process-local authentication caches, closes that process’s LDAP connections, and does not revoke an existing browser cookie.
Browser sign-in, credential limits and caching
Sign-in form protection
Section titled “Sign-in form protection”The sign-in page accepts a submitted form only from its own pages. A form posted from another website shows “Invalid request” and creates no session, so a third-party page cannot sign a visitor’s browser into a different account. Sign-out has the same check: a request from another website shows “Invalid request” and leaves the current session in place. Rejected attempts are logged with the auth_login_cross_origin_rejected or auth_logout_cross_origin_rejected warning.
Over HTTPS, current browsers report where a request came from, so sign-in and sign-out behind a reverse proxy need no extra configuration. Over plain HTTP, and in older browsers that do not report it, such as Safari before 16.4, a request is checked against the address the browser opened instead. Behind a reverse proxy, Scribe knows that public address when http.requested-uri-discovery is enabled, the proxy’s address is listed in the trusted proxies, and the proxy sends either Forwarded with proto and host (for example, Forwarded: for=203.0.113.7;proto=https;host=scribe.example.com) or X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host. The proxy must set these headers itself and remove any Forwarded header sent by the client. For X-Forwarded-For, it must report the client address; any other address in the chain must also be a trusted proxy. Without a trusted proxy reporting the public address, these requests show “Invalid request” when signing in or out.
Sign-in and sign-out POST requests without origin information are rejected. Use HTTP Basic for scripted access. HTTP Basic, OIDC sign-in, and LDAP bind are not affected.
Observe actions that change state — Inbox actions, the plan-mode kill switch, and heap dumps — follow the same rule when you use them from a browser session: a request from another website, or one without origin information, is rejected with 403 and changes nothing. Requests with a bearer token or HTTP Basic credentials are not affected. Send JSON bodies with Content-Type: application/json; Inbox actions and the kill switch answer other content types with 415.
Over HTTPS, a browser session uses only the protected session cookie that Scribe sets over HTTPS. A session cookie from a plain-HTTP sign-in is ignored there, so sign in again after moving a deployment from HTTP to HTTPS. Behind a reverse proxy that terminates TLS, Scribe treats a request as HTTPS only when the proxy is a trusted proxy as described above and reports https; without that, sessions use the plain cookie without the Secure attribute.
Request size limits
Section titled “Request size limits”Over HTTP, credentials are limited by the size of the request that carries them, which is lower than on the LDAP listener:
- The browser sign-in form accepts at most 16 KiB in total, for the username, the password, and the page to return to. A larger form gets
413and no credential is checked. - HTTP Basic credentials travel in the
Authorizationheader and must fit the request-header limit,http.protocols.http-1-1.max-headers-size, 16 KiB by default. - Any request body larger than 1 MiB is refused: the client gets
413, or the connection may be closed before a response. Change the limit per socket withhttp.request-limits.max-payload-size, or set-1to remove it.
Within these bounds, a directory username larger than 8 KiB is refused like a wrong password: HTTP Basic gets 401, and the sign-in form shows “Invalid credentials”. The LDAP listener accepts larger credentials; see its size limits.
Authentication caching
Section titled “Authentication caching”auth.cache provides inherited defaults for the LDAP, ROPC, and opaque bearer-token introspection caches, with method-specific overrides under auth.ldap.cache, auth.ropc.cache, and auth.bearer.cache. LDAP cache expiry starts when the backend check succeeds; a cache hit does not extend it. Failed, expired, timed-out, or abandoned checks never become reusable successes. Setting a method TTL to 0s disables its result cache while simultaneous LDAP requests for the exact same credentials can still share one bounded backend check. JWT validation keeps its existing key-cache behavior; there is no additional global result cache.
To end a browser session, log out or wait for auth.session.session-ttl.
Access rules
Section titled “Access rules”Access rules let you control who can do what. Rules evaluate top-to-bottom; first match wins. If nothing matches, access is denied.
Out of the box, Scribe allows authenticated requests and denies anonymous access. Prometheus and health endpoints are exceptions — they allow anonymous access for scrapers and Kubernetes.
auth.rules = [ { id = "admin-bypass", action = allow, where = "subject.roles = admin" } { id = "schema-public", action = allow, where = "request.channel = graphql and request.operation = schema" } { action = allow, where = "subject.authenticated = true and request.operation in [search, lookup]" }]Each rule takes action (allow/deny), an optional where filter expression, and an optional id for log/trace visibility. Values in a rule are compared literally and without regard to case. Only * in a wildcard (*=) value stands for any text; every other character, including _ and %, matches itself.
Common patterns
Section titled “Common patterns”Authenticated access from the internal network only:
auth.rules = [ { action = allow, where = "subject.authenticated = true and request.client.ip startswith 10.0." }]Health probes keep their own anonymous rule in monitoring.health.auth.rules, so they need no entry here.
Restrict history queries to admins:
auth.rules = [ { action = allow, where = "subject.roles = admin" } { action = deny, where = "request.operation = history" } { action = allow, where = "subject.authenticated = true" }]LDAP writes require admin role:
channels.ldap.auth.rules = [ { action = allow, where = "subject.roles = admin" } { action = deny, where = "request.operation = modify or request.operation = delete" } { action = allow, where = "subject.authenticated = true" }]Related
Section titled “Related”- Auth configuration reference — All settings: access rule attributes, identity model, LDAP role mapping, credential caching, JWT validation, browser sessions, multi-provider setup, channel overrides
- Production checklist — TLS, network isolation, token validation hardening
- API & Networking — TLS and socket configuration
- Error Handling — Auth error codes and response formats