SAML 2.0

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

Setup

1. Gather IdP metadata

Your IdP admin should provide one of:

• Metadata URL (e.g., https://idp.example.com/metadata) — preferred, auto-refreshes
• Metadata XML file — if the IdP can’t expose a URL

2. Configure TapPass

saml:
  # One of these:
  idp_metadata_url: https://idp.example.com/saml/metadata
  idp_metadata_file: /etc/tappass/idp-metadata.xml

  # Service Provider config
  entity_id: https://tappass.example.com
  acs_url: https://tappass.example.com/saml/acs
  slo_url: https://tappass.example.com/saml/slo

  # Access control
  allowed_domains:
    - yourcompany.com

  # Optional: require signed assertions (recommended)
  require_signed_assertion: true
  require_signed_response: false

  # Optional: require encrypted assertions
  require_encrypted_assertion: false

3. Register TapPass as a Service Provider in your IdP

Give your IdP admin:

Field	Value
Entity ID	https://tappass.example.com
ACS URL	https://tappass.example.com/saml/acs
SLO URL (optional)	https://tappass.example.com/saml/slo
NameID format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Signed assertion	Required
Binding	HTTP-POST

Or point them at TapPass’s SP metadata:

https://tappass.example.com/saml/metadata

4. Attribute mapping

TapPass reads standard claims. Ask your IdP admin to send:

Attribute	Claim name	Required
Email	email or emailAddress	Yes
Full name	name	No
Groups	groups or memberOf	For role mapping

Role mapping

saml:
  role_mapping:
    "CN=tappass-admins,OU=Groups,DC=example,DC=com": admin
    "tappass-viewers": viewer

Replay protection

TapPass maintains a short-window cache of assertion IDs and rejects any duplicate within the assertion’s validity period. No extra config needed.

Signature verification

On every assertion:

• XML signature verified against IdP certificate (from metadata)
• Issuer matches IdP entity ID
• Audience matches TapPass entity ID
• NotBefore / NotOnOrAfter respected (5-minute clock skew)

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

Common IdPs

Concrete steps live on provider pages:

• Azure AD (Entra ID) SAML
• Okta SAML
• OneLogin, JumpCloud, PingFederate, ADFS — use the generic setup above; the admin-side fields are identical.