Configure SSO and external authentication

By default, access to your Secret Manager instance is via an admin token. To strengthen security and centralize identity management, you can configure external authentication methods on your OpenBao instance: LDAP, OIDC or JWT.

This guide explains how to enable and configure these authentication methods to set up SSO (Single Sign-On).

info

The commands in this guide use the OpenBao CLI (bao). You can also perform these operations via the OpenBao HTTP API or the instance's web interface.

Prerequisites

• A Secret Manager instance in the RUNNING state;
• The instance's admin token;
• The bao CLI installed and configured:

  export BAO_ADDR="https://{instance-host}"
  export BAO_TOKEN="{admin-token}"

---

Enable an authentication method

Before configuring an authentication method, you must enable it on the instance:

bao auth enable ldap

or:

bao auth enable oidc

or:

bao auth enable jwt

To check which authentication methods are enabled:

bao auth list

tip

You can enable several authentication methods simultaneously on the same instance.

---

Configure LDAP authentication

The LDAP method authenticates users via an LDAP directory (Active Directory, OpenLDAP, etc.).

Configuring the LDAP connection

bao write auth/ldap/config \
  url="ldaps://ldap.example.com:636" \
  binddn="cn=openbao,ou=ServiceAccounts,dc=example,dc=com" \
  bindpass="{bind-password}" \
  userdn="ou=Users,dc=example,dc=com" \
  userattr="uid" \
  groupdn="ou=Groups,dc=example,dc=com" \
  groupattr="cn" \
  groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" \
  insecure_tls=false \
  starttls=false \
  tls_min_version="tls12" \
  tls_max_version="tls12"

Main parameters

Parameter	Description
url	LDAP server URL (use ldaps:// for TLS)
binddn	DN of the service account used for LDAP queries
bindpass	Service account password
userdn	Base DN for user search
userattr	LDAP attribute used as the identifier (e.g. uid, sAMAccountName)
groupdn	Base DN for group search
groupattr	LDAP attribute representing the group name
groupfilter	LDAP filter for searching a user's groups
insecure_tls	Set to true only for testing (disables certificate verification)
starttls	Enable StartTLS for an unencrypted LDAP connection upgraded to TLS
tls_min_version	Minimum accepted TLS version
tls_max_version	Maximum accepted TLS version

warning

In production, always use ldaps:// or starttls=true to encrypt communications with the LDAP server. Never set insecure_tls=true in production.

Create an LDAP policy and group

After configuring the connection, map the LDAP groups to OpenBao policies:

bao policy write admin-policy - <<EOF
path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
EOF

bao write auth/ldap/groups/admin policies="admin-policy"

Test the LDAP connection

bao login -method=ldap username=jdupont

---

Configure OIDC authentication

The OIDC method authenticates users via an OpenID Connect-compatible identity provider (Keycloak, Azure AD, Okta, etc.).

Configuring the OIDC provider

bao write auth/oidc/config \
  oidc_discovery_url="https://keycloak.example.com/realms/myrealm" \
  oidc_client_id="openbao" \
  oidc_client_secret="{client-secret}" \
  default_role="default"

Main parameters

Parameter	Description
oidc_discovery_url	OIDC discovery URL of the identity provider (without .well-known/openid-configuration)
oidc_client_id	Identifier of the OAuth client registered with the provider
oidc_client_secret	OAuth client secret
default_role	Default role used during authentication

info

The redirect URL to configure with the OIDC provider is: https://{instance-host}/ui/vault/auth/oidc/oidc/callback

Create an OIDC role

A role defines the authentication conditions and the associated policies:

bao write auth/oidc/role/default \
  bound_audiences="openbao" \
  allowed_redirect_uris="https://{instance-host}/ui/vault/auth/oidc/oidc/callback" \
  user_claim="sub" \
  groups_claim="groups" \
  policies="default-policy" \
  ttl="1h"

Role parameters

Parameter	Description
bound_audiences	OAuth client identifier that the JWT must contain
allowed_redirect_uris	Redirect URIs allowed after authentication
user_claim	JWT claim used as the user identifier
groups_claim	JWT claim containing the user's groups
policies	OpenBao policies assigned to the user
ttl	Validity period of the token issued by OpenBao

Map OIDC groups to policies

bao write auth/oidc/groups/admin policies="admin-policy"

Test the OIDC connection

Via the web interface, go to the instance URL and select the OIDC method. Or via the CLI:

bao login -method=oidc

---

Configure JWT authentication

The JWT method is similar to OIDC but suited to machine-to-machine flows (no browser redirect). It is suitable for CI/CD pipelines and service accounts.

Configuration with JWKS keys

bao write auth/jwt/config \
  jwks_url="https://keycloak.example.com/realms/myrealm/protocol/openid-connect/certs" \
  bound_issuer="https://keycloak.example.com/realms/myrealm"

Configuration with OIDC discovery

bao write auth/jwt/config \
  oidc_discovery_url="https://keycloak.example.com/realms/myrealm" \
  bound_issuer="https://keycloak.example.com/realms"

Create a JWT role

bao write auth/jwt/role/ci-pipeline \
  bound_audiences="openbao-ci" \
  user_claim="sub" \
  bound_subject="service-account:ci" \
  policies="ci-policy" \
  ttl="30m"

Test JWT authentication

bao write auth/jwt/login jwt="{jwt-token}"

---

Comparison of authentication methods

Method	Use case	Browser SSO	Machine-to-machine flow
LDAP	Existing enterprise directory	No	Yes (bind)
OIDC	SSO identity provider (Keycloak, Azure AD)	Yes	Yes (client credentials)
JWT	CI/CD, service accounts	No	Yes

---

Best practices

Security

• Always use TLS (ldaps:// or starttls) for LDAP connections;
• limit the permissions of LDAP service accounts to the strict minimum (read-only on the directory);
• configure short TTLs for the tokens issued by OpenBao;
• rotate the OIDC client secrets regularly.

High availability

• Configure several upstream LDAP servers via a load balancer to avoid a single point of failure;
• monitor the availability of the OIDC provider — an outage blocks new authentications (existing tokens remain valid until they expire).

Principle of least privilege

• Create specific policies for each role or group;
• grant the admin policies only to administrators;
• use read-only policies for CI/CD service accounts.

---

Troubleshooting

LDAP authentication fails

1. Check the network connectivity between the instance and the LDAP server;
2. check the bind DN and password;
3. test with insecure_tls=true temporarily to rule out a certificate issue;
4. consult the instance logs for the error details.

OIDC authentication returns a redirect error

1. Check that the redirect URI is exactly the one configured in the OIDC provider;
2. check that the client secret is correct;
3. check that the OIDC discovery URL is reachable from the instance.

Groups are not mapped correctly

1. Check the LDAP groupfilter or the OIDC groups_claim;
2. use the bao read auth/{method}/groups command to list the configured groups;
3. check that the group names match between the provider and the OpenBao configuration.