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 exact URL Britive should send users back to after login. Usually derived automatically - set it only in the case described below.
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?

After a user logs in at Britive, Britive needs to send them back to Bridge at a specific web address. Normally Bridge figures out that address on its own by reading the incoming request, including a header (X-Forwarded-Proto) that tells it whether the original request was HTTP or HTTPS.

Some load balancers - specifically Layer 4 network load balancers (L4 NLBs) - forward raw network traffic without adding that header. (A Layer 4 load balancer routes connections by IP and port only; it does not inspect the web request, so it cannot annotate it.) When that header is missing, Bridge can guess the wrong protocol and build a broken return URL. Setting redirect_url explicitly removes the guesswork.

bridge.yaml
server:
  auth:
    britive:
      redirect_url: "https://bridge.acme.com/auth/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