SSO & SAML 2.0 Configuration Guide

TapPass supports three enterprise SSO methods:

Method	Protocol	Best for
OIDC	OpenID Connect	Google Workspace, Azure AD, Okta
SAML 2.0	SAML	Azure AD (Entra ID), Okta, OneLogin, JumpCloud, ADFS
Google Token	JWT verification	Teams already using `gcloud` CLI

All three methods auto-provision accounts on first login.

OIDC (OpenID Connect)

Google Workspace

TAPPASS_SSO_PROVIDER=google
TAPPASS_SSO_CLIENT_ID=your-client-id.apps.googleusercontent.com
TAPPASS_SSO_CLIENT_SECRET=your-client-secret
TAPPASS_SSO_REDIRECT_URI=https://tappass.company.com/sso/callback
TAPPASS_SSO_ALLOWED_DOMAINS=company.com

Setup in Google Cloud Console:

APIs & Services → Credentials → Create OAuth 2.0 Client
Authorized redirect URIs: https://tappass.company.com/sso/callback
Copy Client ID and Client Secret

Azure AD (Entra ID): OIDC

TAPPASS_SSO_PROVIDER=azure
TAPPASS_SSO_CLIENT_ID=your-application-id
TAPPASS_SSO_CLIENT_SECRET=your-client-secret
TAPPASS_SSO_TENANT_ID=your-tenant-id
TAPPASS_SSO_REDIRECT_URI=https://tappass.company.com/sso/callback
TAPPASS_SSO_ALLOWED_DOMAINS=company.com

Setup in Azure Portal:

App registrations → New registration
Redirect URIs: https://tappass.company.com/sso/callback (Web)
Certificates & secrets → New client secret
Copy Application (client) ID, Client secret, and Directory (tenant) ID

Okta. OIDC

TAPPASS_SSO_PROVIDER=okta
TAPPASS_SSO_CLIENT_ID=your-client-id
TAPPASS_SSO_CLIENT_SECRET=your-client-secret
TAPPASS_SSO_ISSUER=https://your-org.okta.com
TAPPASS_SSO_REDIRECT_URI=https://tappass.company.com/sso/callback
TAPPASS_SSO_ALLOWED_DOMAINS=company.com

SAML 2.0

SAML 2.0 is supported for enterprises that require it. Recommended for organizations using ADFS, OneLogin, JumpCloud, or when OIDC is not available.

Quick Setup

Get SP metadata from TapPass:
```
GET https://tappass.company.com/saml/metadata
```
Upload this XML to your IdP.

Configure TapPass with your IdP details:

TAPPASS_SAML_ENABLED=1
TAPPASS_SAML_ENTITY_ID=https://tappass.company.com/saml/metadata
TAPPASS_SAML_ACS_URL=https://tappass.company.com/saml/acs
TAPPASS_SAML_IDP_SSO_URL=https://login.microsoftonline.com/.../saml2
TAPPASS_SAML_IDP_CERT=MIIDb...  # base64 X.509 cert from IdP
TAPPASS_SAML_ALLOWED_DOMAINS=company.com

Test: Visit https://tappass.company.com/saml/login

Auto-Configure from Metadata URL

If your IdP provides a metadata URL, TapPass can auto-extract the SSO URL and certificate:

curl -X POST https://tappass.company.com/saml/configure-from-metadata \
  -H "Authorization: Bearer tp_admin_..." \
  -H "Content-Type: application/json" \
  -d '{"metadata_url": "https://login.microsoftonline.com/.../federationmetadata/2007-06/federationmetadata.xml"}'

Azure AD (Entra ID). SAML

Azure Portal → Enterprise Applications → New Application → Create your own
Single sign-on → SAML
Basic SAML Configuration:
- Identifier (Entity ID): https://tappass.company.com/saml/metadata
- Reply URL (ACS URL): https://tappass.company.com/saml/acs
Download Certificate (Base64) from SAML Signing Certificate
Copy Login URL from Set up section

TAPPASS_SAML_ENABLED=1
TAPPASS_SAML_ENTITY_ID=https://tappass.company.com/saml/metadata
TAPPASS_SAML_ACS_URL=https://tappass.company.com/saml/acs
TAPPASS_SAML_IDP_SSO_URL=https://login.microsoftonline.com/{tenant}/saml2
TAPPASS_SAML_IDP_CERT=MIIDb...  # paste from downloaded cert
TAPPASS_SAML_ALLOWED_DOMAINS=company.com

Okta. SAML

Okta Admin → Applications → Create App Integration → SAML 2.0
General Settings → App name: “TapPass”
SAML Settings:
- Single sign on URL: https://tappass.company.com/saml/acs
- Audience URI: https://tappass.company.com/saml/metadata
- Name ID format: EmailAddress
Attribute Statements:
- email → user.email
- name → user.displayName
Download IdP metadata or copy SSO URL + Certificate

OneLogin. SAML

OneLogin Admin → Applications → Add App → SAML Custom Connector
Configuration:
- ACS URL: https://tappass.company.com/saml/acs
- ACS URL Validator: ^https://tappass\.company\.com/saml/acs$
- Audience: https://tappass.company.com/saml/metadata
SSO tab → Copy SAML 2.0 Endpoint (HTTP) and X.509 Certificate

ADFS. SAML

ADFS Management → Relying Party Trusts → Add Relying Party Trust
Import metadata: https://tappass.company.com/saml/metadata
Or manual:
- Identifier: https://tappass.company.com/saml/metadata
- Endpoint: POST → https://tappass.company.com/saml/acs
Edit Claim Rules:
- Send LDAP Attributes → E-Mail-Addresses, Display-Name

Role Mapping

Map IdP groups to TapPass roles:

TAPPASS_SAML_ROLE_MAPPING="TapPass-Admins=org_admin,Developers=developer,Security=auditor"
TAPPASS_SAML_DEFAULT_ROLE=user

TapPass Role	Permissions
`super_admin`	Full platform access
`org_admin`	Manage policies, agents, audit for their org
`developer`	Register agents, connect accounts
`auditor`	Read-only audit/status
`employee`	App access, self-service account connection

For OIDC, roles are set during account creation. For SAML, roles are resolved from the group assertion on every login.

Attribute Mapping

Default attribute names follow Azure AD conventions. Override for other IdPs:

# Okta / OneLogin
TAPPASS_SAML_ATTR_EMAIL=email
TAPPASS_SAML_ATTR_NAME=displayName
TAPPASS_SAML_ATTR_FIRST_NAME=firstName
TAPPASS_SAML_ATTR_LAST_NAME=lastName
TAPPASS_SAML_ATTR_GROUPS=groups

Security Considerations

Setting	Default	Description
`TAPPASS_SAML_WANT_ASSERTIONS_SIGNED`	`true`	Require IdP to sign assertions
`TAPPASS_SAML_WANT_RESPONSE_SIGNED`	`true`	Require IdP to sign responses
`TAPPASS_SAML_ALLOWED_DOMAINS`	(none)	Restrict logins to specific email domains

Recommendations:

Always enable assertion signing in production
Always set ALLOWED_DOMAINS to prevent unauthorized logins
Use HTTPS for ACS URL (required by most IdPs)
Rotate IdP certificates before expiry

Testing

# Check SAML config
curl https://tappass.company.com/saml/config \
  -H "Authorization: Bearer tp_admin_..."

# Get SP metadata (upload to IdP)
curl https://tappass.company.com/saml/metadata

# Initiate login
open https://tappass.company.com/saml/login

Troubleshooting

Issue	Solution
”SAML is not configured”	Set `TAPPASS_SAML_ENABLED=1` and restart
Signature verification failed	Check IdP certificate is correct (base64, no headers)
Assertion expired	Check server clock sync (NTP). Max skew: 5 minutes
Domain rejected	Add domain to `TAPPASS_SAML_ALLOWED_DOMAINS`
No email in assertion	Check IdP attribute mapping. Try `TAPPASS_SAML_ATTR_EMAIL=email`