Skip to content
TapPass

SAML 2.0

TapPass implements standard SAML 2.0 Service Provider flow — SP-initiated, HTTP-POST binding, signed assertions. Works with Okta, Entra ID, OneLogin, JumpCloud, PingFederate, ADFS, and any SAML-compliant IdP.

Endpoints

Section titled “Endpoints”
Endpoint Purpose
GET /saml/login Starts the flow — generates an AuthnRequest and redirects to the IdP
POST /saml/acs Assertion Consumer Service — the IdP POSTs the SAMLResponse here
GET /saml/metadata TapPass SP metadata (point your IdP at it)

Enabled only when TAPPASS_SAML_ENABLED=1.

Setup

Section titled “Setup”

1. Gather IdP details

Section titled “1. Gather IdP details”

Your IdP admin should provide one of:

  • Metadata URL (e.g., https://idp.example.com/saml/metadata) — preferred, auto-refreshes
  • SSO URL + X.509 certificate — if the IdP can’t expose a metadata URL

2. Configure TapPass

Section titled “2. Configure TapPass”
Terminal window
TAPPASS_SAML_ENABLED=1


# Service Provider
TAPPASS_SAML_ENTITY_ID=https://tappass.example.com/saml/metadata
TAPPASS_SAML_ACS_URL=https://tappass.example.com/saml/acs


# IdP — one of these:
TAPPASS_SAML_IDP_METADATA_URL=https://idp.example.com/saml/metadata
# or:
TAPPASS_SAML_IDP_SSO_URL=https://idp.example.com/sso/saml
TAPPASS_SAML_IDP_CERT=<base64 X.509 cert>


# Access control
TAPPASS_SAML_ALLOWED_DOMAINS=yourcompany.com          # optional, comma-separated
TAPPASS_SAML_DEFAULT_ROLE=user                        # role when no mapping fires


# Signature requirements (defaults; never disable in production)
TAPPASS_SAML_WANT_ASSERTIONS_SIGNED=true
TAPPASS_SAML_WANT_RESPONSE_SIGNED=true


# Group → role mapping: 'group=role,group=role'
TAPPASS_SAML_ROLE_MAPPING="tappass-admins=admin,tappass-viewers=viewer"

3. Register TapPass as a Service Provider in your IdP

Section titled “3. Register TapPass as a Service Provider in your IdP”

Give your IdP admin:

Field Value
Entity ID your TAPPASS_SAML_ENTITY_ID
ACS URL https://tappass.example.com/saml/acs
SP metadata https://tappass.example.com/saml/metadata
NameID format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Signed assertion Required
Binding HTTP-POST

4. Attribute mapping

Section titled “4. Attribute mapping”

TapPass reads these attribute names by default (all overridable via TAPPASS_SAML_ATTR_*):

Attribute Default claim name Required
Email .../claims/emailaddress Yes
Display name .../claims/name No
First / last name .../claims/givenname / .../claims/surname No
Groups .../claims/groups For role mapping

Signature verification

Section titled “Signature verification”

On every assertion:

  • XML signature verified against the IdP certificate (from metadata or TAPPASS_SAML_IDP_CERT)
  • Issuer matches the IdP entity ID
  • Audience matches the TapPass entity ID
  • NotBefore / NotOnOrAfter respected

If any check fails, the login is rejected and logged to the audit trail.

Common IdPs

Section titled “Common IdPs”

Concrete steps live on provider pages: