Azure AD (Entra ID)

TapPass supports both OIDC (recommended) and SAML 2.0 with Entra ID. OIDC is multi-tenant: set the tenant to organizations for B2B SaaS, or pin it to your own tenant ID.

OIDC setup

1. Register an Entra app

Azure portal → Entra ID → App registrations → New registration
Name: TapPass
Redirect URI (Web): https://tappass.example.com/sso/callback

Save and note:

Application (client) ID
Under Certificates & secrets, create a new client secret

2. Configure TapPass

# Server environment
TAPPASS_SSO_PROVIDERS=azure
TAPPASS_SSO_AZURE_CLIENT_ID=<app-guid>
TAPPASS_SSO_AZURE_CLIENT_SECRET=<secret>
TAPPASS_SSO_AZURE_TENANT_ID=organizations   # default; or your tenant ID
TAPPASS_SSO_REDIRECT_URI=https://tappass.example.com/sso/callback
TAPPASS_SSO_ALLOWED_DOMAINS=yourcompany.com,subsidiary.com   # optional

3. Test

curl https://tappass.example.com/sso/login?provider=azure
# redirects to Entra consent page

The full flow is /sso/login → IdP → /sso/callback → POST /sso/exchange, which returns the TapPass session token.

SAML setup

Use SAML when your Entra tenant enforces federation through a gallery app.

1. Create an Entra enterprise app

Entra ID → Enterprise applications → New application → Create your own
Single sign-on method: SAML
Identifier (Entity ID): your TAPPASS_SAML_ENTITY_ID
Reply URL (ACS): https://tappass.example.com/saml/acs

2. Configure TapPass

TAPPASS_SAML_ENABLED=1
TAPPASS_SAML_ENTITY_ID=https://tappass.example.com/saml/metadata
TAPPASS_SAML_ACS_URL=https://tappass.example.com/saml/acs
TAPPASS_SAML_IDP_METADATA_URL=https://login.microsoftonline.com/<tenant>/federationmetadata/2007-06/federationmetadata.xml
# or pin the IdP directly:
# TAPPASS_SAML_IDP_SSO_URL=...
# TAPPASS_SAML_IDP_CERT=<base64 X.509 cert>
TAPPASS_SAML_ALLOWED_DOMAINS=yourcompany.com

See the SAML 2.0 page for the full env reference, including group → role mapping.

3. Assign users / groups

Entra → Enterprise applications → TapPass → Users and groups → Add user/group. Only assigned users can log in.

Troubleshooting

Symptom	Likely cause
`AADSTS50011` redirect URI mismatch	Redirect URL in TapPass config doesn’t match the Entra app
User sees “domain not allowed”	`TAPPASS_SSO_ALLOWED_DOMAINS` doesn’t include the user’s email domain
SAML signature errors	`TAPPASS_SAML_IDP_CERT` / metadata URL stale — re-download the federation metadata