Set up SAML SSO with Okta

Configure the Okta application and send the right metadata and group mappings to Webless.

Webless handles the Firebase SAML configuration. Your team only needs to configure the Okta app and send the resulting IdP metadata and group mappings.

Prerequisites

• Okta admin access
• Your SAML provider ID from Webless
• The ACS URL from Webless

Configure Okta

1. Collect the values from Webless

   Webless will provide:

   • Your SAML provider ID, such as saml.okta.client1
   • The ACS URL, such as https://webless-frontend.firebaseapp.com/__/auth/handler
2. Create the SAML app in Okta

   In Okta, create a new SAML 2.0 app integration and use the provider ID in the app name so the app is easy to identify.

3. Enter the required SAML settings

   Use these values exactly.

   Field	Value
   Single Sign On URL	https://webless-frontend.firebaseapp.com/__/auth/handler
   Recipient URL	https://webless-frontend.firebaseapp.com/__/auth/handler
   Audience Restriction	Your exact provider ID
   Name ID Format	EmailAddress
   Application username	Email

4. Add attributes and groups

   Add the following attribute statements:

   Name	Format	Value
   email	Unspecified	user.email
   firstName	Unspecified	user.firstName
   lastName	Unspecified	user.lastName

   Then add a group attribute statement so Okta emits the full group list:

   Name	Format	Filter
   groups	Unspecified	.*

5. Assign groups and users

   Create and assign your admin and user groups to the SAML app. Common examples include:

   • Admin groups: admin, administrator, team_lead, managers
   • User groups: user, employee, staff, general
6. Send the IdP metadata to Webless

   Send all of the following to Webless:

   • The Okta SSO URL
   • The Entity ID or Issuer
   • The full X.509 certificate
   • The list of admin group names
   • The list of user group names
   • Your email domain
   • Your authentication preferences for SAML, Google login, and password login
7. Test login

   After Webless enables your domain, sign in with SSO and verify the expected role assignment.

   • Admin users should receive {domain}_admin
   • Regular users should receive {domain}_user

Troubleshooting

Groups are not being sent

• Verify the group attribute statement exists
• Verify users are assigned to the correct Okta groups
• Verify those groups are assigned to the SAML application

Users receive the wrong roles

• Verify the group names you gave Webless exactly match the group names in Okta
• Verify the affected users belong to the expected groups

Audience restriction errors appear

The Audience URI in Okta must exactly match the provider ID Webless gave you, including case.