This guide explains how to configure Honeydipper with the built-in auth-saml driver so Honeydipper acts as a SAML Service Provider (SP).
The auth-saml driver provides four RPC handlers:
saml_login: creates a redirect URL for SP-initiated login.saml_acs: validates SAMLResponse and returns a Honeydipper session token.auth_web_request: validates session token from Authorization: Bearer ... and returns principal data to API middleware.saml_sp_metadata: returns SP metadata XML for IdP configuration.When SAML login is complete, Honeydipper API authorization still uses Casbin, so SSO and authorization policy remain separate.
drivers.auth-saml.jwt_signing_key or AUTH_SAML_JWT_SIGNING_KEY).When using this repository version, API service includes these local endpoints:
GET /api/auth/saml/loginGET /api/auth/saml/metadataPOST /api/auth/saml/callbackGET /api/auth/saml/callbackTypical usage:
/api/auth/saml/login and redirects browser to redirect_url./api/auth/saml/metadata into the IdP./api/auth/saml/callback.Authorization header for API calls.Example daemon config snippet:
drivers:
daemon:
featureMap:
global:
eventbus: redisqueue
drivers:
auth-saml:
name: auth-saml
type: builtin
handlerData:
shortName: auth-saml
services:
api:
auth-providers:
- auth-saml
auth:
casbin:
models:
- |
[request_definition]
r = sub, principal, obj, act, provider
[policy_definition]
p = sub, obj, act, provider
[role_definition]
g = _, _
[policy_effect]
e = some(where (p.eft == allow))
[matchers]
m = (r.sub == p.sub && r.obj == p.obj && r.act == p.act && r.provider == p.provider) \
|| (g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act && r.provider == p.provider)
policies:
- |
p, everyone, user/profile, read, auth-saml
g, alice@example.com, everyone
Driver data snippet:
drivers:
auth-saml:
acs_url: https://hd.example.com/api/auth/saml/callback
idp_metadata_url: https://idp.example.com/metadata
# Optional: defaults to acs_url
entity_id: https://hd.example.com/saml/sp
# Optional: defaults to false
allow_idp_initiated: false
# Optional: seconds, default 86400
token_expiration: 86400
# Optional: seconds, default 600
request_ttl: 600
# Recommended via env var in production
jwt_signing_key: change-me-to-a-strong-random-value
Environment variable alternative:
export AUTH_SAML_JWT_SIGNING_KEY='replace-with-a-strong-random-secret'
Because API auth can now pass a principal object (r = sub, principal, obj, act, provider), you can write claim-based rules.
Example using SAML assertion attributes in r.principal.Data:
[matchers]
m = (
r.obj == p.obj &&
r.act == p.act &&
r.provider == p.provider &&
r.principal.Data["groups"] == "platform-admins"
)
Important note for multi-value attributes:
If your IdP sends group values as a list, match with list-aware logic in model expressions.
GET /api/auth/saml/login.driver:auth-saml/saml_login and returns redirect_url./api/auth/saml/callback.driver:auth-saml/saml_acs.Authorization: Bearer <token>.driver:auth-saml/auth_web_request for each request.jwt_signing_key out of git; prefer environment variable or secret manager.allow_idp_initiated disabled unless your flow explicitly requires IdP-initiated login.request_ttl short (default 10 minutes) to reduce replay window for stale relay states.