Skip to content
Britive Bridge
Configuration
Authentication

Authentication

Authentication controls how users prove who they are when they open the Bridge web interface. Bridge supports two login methods: Britive (single sign-on through your Britive tenant) and LDAP (your directory server, such as Active Directory or OpenLDAP). You can enable one or both.

All authentication settings live under server.auth.

Choosing login methods

The server.auth.types setting is a list of the login methods you want to offer.

OptionTypeDefaultDescription
server.auth.typeslist of strings["britive"]Which login methods are enabled. Valid values are britive and ldap. An empty list disables web login entirely.

When both are listed, users see a choice of how to sign in.

bridge.yaml
server:
  auth:
    types:
      - britive
      - ldap

Britive (single sign-on)

This method sends users to your Britive tenant to log in, then returns them to Bridge already authenticated. It uses OAuth, the standard “Log in with…” handshake you have seen across the web. Settings live under server.auth.britive.

OptionTypeDefaultDescription
server.auth.britive.tenantstring""Your Britive tenant. Required when Britive login is enabled. Accepts either just the subdomain (for example acme) or the full URL (for example https://acme.britive-app.com). Can also be set with the BRITIVE_TENANT environment variable.
server.auth.britive.scopeslist of strings["openid"]The OAuth scopes Bridge requests. The default is correct for most deployments.
server.auth.britive.redirect_urlstring""The full OAuth callback URL, including /api/auth/britive/callback. If unset, Bridge derives it from the incoming request.
server.auth.britive.client_idstring""The OAuth client identifier. If left empty, Bridge derives it automatically.
server.auth.britive.client_id_prefixstring"britive-bridge-"The prefix used when deriving client_id. Leave this at its default unless Britive support tells you otherwise.

When do I need to set redirect_url?

Bridge handles Britive OAuth callbacks at /api/auth/britive/callback in every deployment type. Setting redirect_url supplies the full URL to Britive; it does not change the route Bridge handles.

By default, Bridge uses the request hostname and selects HTTPS when the connection uses TLS or the request includes X-Forwarded-Proto: https. A load balancer that terminates TLS and forwards HTTP without that header can cause Bridge to derive an HTTP callback URL.

Set redirect_url explicitly when the proxy does not preserve the original hostname or scheme, or when you want a fixed callback URL:

bridge.yaml
server:
  auth:
    britive:
      redirect_url: "https://bridge.acme.com/api/auth/britive/callback"

For a Helm deployment, set config.auth.britive.redirectUrl:

values.yaml
config:
  auth:
    britive:
      redirectUrl: "https://bridge.acme.com/api/auth/britive/callback"

The equivalent environment variable is BRIDGE_SERVER_AUTH_BRITIVE_REDIRECT_URL.

Use the same HTTPS hostname to start login and receive the callback. Bridge marks its login nonce and session cookies Secure by default, so the browser cannot send them over HTTP on a deployed hostname. Keep server.secure_cookies enabled for production. Your load balancer or gateway can terminate TLS and forward HTTP internally to Bridge.

Setting redirect_url does not configure TLS. Changing only the callback URL to HTTPS while starting login over HTTP does not fix the missing cookie.

Verify the callback

After applying the configuration, start a fresh login from your Bridge HTTPS URL. In the browser’s Network panel, verify that both /api/auth/britive/login and /api/auth/britive/callback use HTTPS and the same hostname. A successful callback redirects to the requested Bridge page.

If the callback returns 401, check the Bridge logs, or the proxy pod or task logs in a clustered deployment. A Britive code exchange failed entry with error="no login nonce presented" and had_nonce=false means the browser did not return the login nonce cookie. Check for an HTTP login or callback, or a hostname change during login. After correcting the URL or TLS configuration, start a new login instead of reloading the failed callback.

About client_id derivation

You usually do not set client_id yourself. When it is empty, Bridge builds one by combining client_id_prefix with your tenant - so the default prefix britive-bridge- plus tenant acme yields britive-bridge-acme. Set client_id directly only if Britive has provisioned a specific identifier for you.

Britive-only example

bridge.yaml
server:
  auth:
    types:
      - britive
    britive:
      tenant: "acme"

LDAP (directory login)

This method checks usernames and passwords against your directory server. LDAP (Lightweight Directory Access Protocol) is the protocol most directory servers, including Active Directory, speak. Settings live under server.auth.ldap.

OptionTypeDefaultDescription
server.auth.ldap.serverstring""The directory server URL. Required. Use ldap://host:389 for a standard connection or ldaps://host:636 for an always-encrypted one.
server.auth.ldap.tlsboolfalseWhen true, upgrade an ldap:// connection to encryption using StartTLS (encrypting an initially plain connection in place). Not needed if you already use ldaps://.
server.auth.ldap.bind_dnstring""The “service account” Bridge uses to search the directory, written as a distinguished name (a directory path, for example cn=bridge,ou=service,dc=acme,dc=com). Required.
server.auth.ldap.bind_passwordstring""Password for the bind account. Set this with the BRIDGE_LDAP_BIND_PASSWORD environment variable rather than in the file.
server.auth.ldap.base_dnstring""The directory branch under which Bridge searches for users (for example ou=people,dc=acme,dc=com). Required.
server.auth.ldap.user_filterstring"(uid={{username}})"The search pattern that finds a user’s directory entry. {{username}} is replaced with what the user typed. For Active Directory you might use (sAMAccountName={{username}}).
server.auth.ldap.tls_insecureboolfalseSkip verification of the directory server’s certificate. Development only - never use in production, as it disables a key security check.

Keep the bind password out of your config file. Provide it through the BRIDGE_LDAP_BIND_PASSWORD environment variable instead.

Failed-login protection. Repeated failed logins from the same client are temporarily locked out (the response is 429 Too Many Requests with a Retry-After header) to slow credential guessing; a successful login clears the counter. Failed attempts are logged at warn, so they’re visible at the default log level for alerting.

LDAP-only example

bridge.yaml
server:
  auth:
    types:
      - ldap
    ldap:
      server: "ldaps://ldap.acme.com:636"
      bind_dn: "cn=bridge,ou=service,dc=acme,dc=com"
      base_dn: "ou=people,dc=acme,dc=com"
      user_filter: "(uid={{username}})"

Provide the bind password separately:

terminal
export BRIDGE_LDAP_BIND_PASSWORD='your-bind-account-password'

Enabling both methods

You can offer Britive single sign-on and LDAP side by side. Configure each block, and list both under types.

bridge.yaml
server:
  auth:
    types:
      - britive
      - ldap
    britive:
      tenant: "acme"
    ldap:
      server: "ldaps://ldap.acme.com:636"
      bind_dn: "cn=bridge,ou=service,dc=acme,dc=com"
      base_dn: "ou=people,dc=acme,dc=com"
      user_filter: "(uid={{username}})"
Last updated on
Environment Variables