Azure AD (Entra ID)

TapPass supports both OIDC (recommended) and SAML 2.0 with Entra ID. OIDC is simpler to maintain and handles refresh tokens natively.

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
• Directory (tenant) ID
• Under Certificates & secrets, create a new client secret

2. Configure TapPass

# Server environment
AZURE_AD_TENANT_ID=<tenant-guid>
AZURE_AD_CLIENT_ID=<app-guid>
AZURE_AD_CLIENT_SECRET=<secret>
AZURE_AD_ALLOWED_DOMAINS=yourcompany.com,subsidiary.com

Or in config/identity.yaml:

sso:
  provider: azure_ad
  tenant_id: "${AZURE_AD_TENANT_ID}"
  client_id: "${AZURE_AD_CLIENT_ID}"
  client_secret: "${AZURE_AD_CLIENT_SECRET}"
  allowed_domains:
    - yourcompany.com

3. Test

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

SAML setup

Use SAML when your Entra tenant enforces federation through a gallery app, or you want SAML assertion encryption.

1. Create an Entra gallery app (Non-gallery)

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

Download the Federation Metadata XML.

2. Configure TapPass

saml:
  idp_metadata_url: https://login.microsoftonline.com/<tenant>/federationmetadata/2007-06/federationmetadata.xml
  entity_id: https://tappass.example.com
  acs_url: https://tappass.example.com/saml/acs
  allowed_domains:
    - yourcompany.com

Or point at a local metadata file:

saml:
  idp_metadata_file: /etc/tappass/entra-metadata.xml

3. Assign users / groups

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

Group → role mapping

Map Entra groups to TapPass roles:

sso:
  role_mapping:
    "tappass-admins": admin
    "tappass-viewers": viewer
    "tappass-operators": operator

The group claim comes from Entra’s groups claim — enable it in Token configuration → Add groups claim.

Troubleshooting

Symptom	Likely cause
AADSTS50011 redirect URI mismatch	ACS / redirect URL in TapPass config doesn’t match the Entra app
User sees “domain not allowed”	allowed_domains doesn’t include the user’s email domain
No groups in session	Groups claim not configured in Entra token settings