Okta

OIDC setup

1. Create an Okta app

• Okta admin → Applications → Create App Integration
• OIDC — OpenID Connect → Web Application
• Sign-in redirect URI: https://tappass.example.com/sso/callback
• Sign-out redirect URI: https://tappass.example.com/sso/logout
• Grant type: Authorization Code

Save and note the Client ID, Client Secret, and your Okta domain (e.g. dev-12345.okta.com).

2. Configure TapPass

OKTA_ISSUER=https://dev-12345.okta.com
OKTA_CLIENT_ID=<client-id>
OKTA_CLIENT_SECRET=<client-secret>
OKTA_ALLOWED_DOMAINS=yourcompany.com

Or:

sso:
  provider: okta
  issuer: "${OKTA_ISSUER}"
  client_id: "${OKTA_CLIENT_ID}"
  client_secret: "${OKTA_CLIENT_SECRET}"
  allowed_domains:
    - yourcompany.com

3. Assign users

Okta → Applications → TapPass → Assignments → Assign to People/Groups.

SAML setup

1. Create SAML app in Okta

• Applications → Create App Integration → SAML 2.0
• SSO URL: https://tappass.example.com/saml/acs
• Audience URI: https://tappass.example.com
• Name ID format: EmailAddress

Download the IdP metadata XML.

2. Configure TapPass

saml:
  idp_metadata_file: /etc/tappass/okta-metadata.xml
  entity_id: https://tappass.example.com
  acs_url: https://tappass.example.com/saml/acs
  allowed_domains:
    - yourcompany.com

Group → role mapping

Push Okta groups as a claim in the OIDC token:

Security → API → Authorization Servers → default → Claims → Add claim:

• Name: groups
• Include in: ID Token
• Value type: Groups
• Filter: Matches regex .*

Then map in TapPass:

sso:
  role_mapping:
    "TapPass Admins": admin
    "TapPass Viewers": viewer