Skip to content

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.

Choose how your clients sign in before configuring access rules.

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.

Your client…UseWhy
Already has a JWT from your IdPBearerFastest — no network calls per request
Sends username/password, needs OAuth claimsROPCTrades credentials for JWT, gets roles/scopes from IdP
Sends username/password, no IdP availableLDAPDirect validation against directory
Repeatedly uses one technical accountLocalValidates configured credentials without a backend authentication request

Use Bearer tokens unless clients can’t obtain tokens themselves.

Two environment variables enable authentication with Bearer tokens:

Terminal window
SCRIBE_AUTH_ENABLED=true
SCRIBE_AUTH_ISSUER=https://auth.example.com/realms/mycompany

Or 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

Clients authenticate by sending an HTTP Authorization header. Scribe supports two header schemes:

SchemeHeader formatWhat Scribe receives
BearerAuthorization: Bearer <jwt>A pre-obtained JWT token
BasicAuthorization: Basic <base64>Username and password (base64-encoded)

The authentication method determines how Scribe validates what it receives:

MethodHeaderValidation
Bearer tokensBearerVerify JWT signature via JWKS, check claims
ROPCBasicExchange credentials with IdP for JWT, then verify
LDAP bindBasicSearch for user DN, bind to LDAP to verify password
Local accountBasicCompare with a configured account; no backend bind

Scribe tries the configured Basic methods in order, but a matching local account decides alone:

Basic credentialsname · passwordLocal account?DN or usernamePassword checklocal accountNext Basic methodldap or ropcRejectedno other methodSigned-in identityAccess rulesfirst match winslooks upmatchesunknown namewrongcorrectverifieschecked by
Basic credentialsname · passwordLocal account?DN or usernamePassword checklocal accountNext Basic methodldap or ropcRejectedno other methodSigned-in identityAccess rulesfirst match winslooks upmatchesunknown namewrongcorrectverifieschecked by
A matching local account accepts or rejects its credentials without trying another method.

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.

Clients obtain a JWT from your identity provider and include it in requests:

GET /api/entries/users HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1...
  1. Client authenticates with IdP (browser redirect, client credentials, etc.)
  2. IdP issues a signed JWT
  3. Client sends JWT to Scribe in the Authorization header
  4. Scribe verifies signature against IdP’s public keys (cached from JWKS)
  5. Scribe checks expiration, audience, and issuer claims

No per-request calls to the IdP. After the initial JWKS fetch, validation happens locally.

ClientIdentity providerScribesignature · claimssigns inissues JWTbearer tokenkeys, cached
ClientIdentity providerScribesignature · claimssigns inissues JWTbearer tokenkeys, cached
Scribe checks a bearer token's signature with cached IdP keys and its expiry, audience, and issuer claims, without calling the IdP for each request.
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.1
Authorization: Basic YWxpY2U6c2VjcmV0
ClientScribevalidates · cachesIdentity providername · passwordexchangesreturns JWT
ClientScribevalidates · cachesIdentity providername · passwordexchangesreturns JWT
With ROPC, Scribe exchanges the client's username and password at the IdP for a token, then validates that token like a bearer token.

Configuration:

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

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.1
Authorization: Basic YWxpY2U6c2VjcmV0

No 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.

ClientScriberesult cachedService accountldap.bind-dnDirectoryname · passwordlooks up DNsearchesbinds as user
ClientScriberesult cachedService accountldap.bind-dnDirectoryname · passwordlooks up DNsearchesbinds as user
Scribe finds the user's DN with its service account, then binds as that user to verify the password.

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:

KEEP WORKINGLDAP sign-innot cachedDirectoryDirectory checkby ScribeFail fastLDAP 52 · HTTP 503Local accountsBrowser sessionsCached sign-insLocal searcheswaits ≤ 10 s5 failuresno answerafter 10 sanswered
KEEP WORKINGLDAP sign-innot cachedDirectoryDirectory checkby ScribeFail fastLDAP 52 · HTTP 503Local accountsBrowser sessionsCached sign-insLocal searcheswaits ≤ 10 s5 failuresno answerafter 10 sanswered
A directory outage stops new uncached LDAP sign-ins while local accounts, browser sessions, cached sign-ins, and locally served searches keep working; searches forwarded to the directory need it.

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 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.methodsThe 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

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.

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 413 and no credential is checked.
  • HTTP Basic credentials travel in the Authorization header 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 with http.request-limits.max-payload-size, or set -1 to 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.

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.

AUTHENTICATION CACHEBROWSER SESSIONLDAP CONNECTIONBackend check succeedsCache entry expireshits don't extendBrowser loginLogout or session TTLLDAP bindNext bindchecks againTTL runssession lastsidentity holds
AUTHENTICATION CACHEBROWSER SESSIONLDAP CONNECTIONBackend check succeedsCache entry expireshits don't extendBrowser loginLogout or session TTLLDAP bindNext bindchecks againTTL runssession lastsidentity holds
Authentication cache expiry does not end an existing browser session or authenticated LDAP connection.

To end a browser session, log out or wait for auth.session.session-ttl.

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.

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" }
]