Custom SAML SSO

Wristband's Custom SAML IdP integration connects any SAML 2.0-compliant identity provider to a specific tenant, enabling Single Sign-On (SSO). It's ideal for customers whose identity provider isn't natively supported by Wristband, such as Google Workspace, Microsoft Entra ID, or Okta Workforce.

Step 1: Create the Custom IdP in Wristband

1. In the Wristband dashboard:
   • Enter Tenant View for the tenant.
   • Navigate to Identity Providers > Enterprise.
   • Select the Custom IdP tab and click the Add IdP button.

2. Configure the following fields in the Create New Enterprise IdP modal:
   • IdP Name: A unique identifier for this IdP within the tenant. The name will be prefixed with ent:custom: automatically. You only need to provide the suffix (e.g., my-saml-idp).
   • Display Name: The name shown to users on any Wristband-hosted UI (e.g., My SAML IdP).
   • Click the Create button.

3. A success screen will display the Wristband SAML service provider details:
   • SP Entity ID: Wristband's unique identifier as a SAML service provider.
   • ACS URL: The endpoint Wristband uses to receive SAML assertions from your IdP.
4. Copy both the SP Entity ID and ACS URL values before proceeding. You'll need them to complete the configuration in Step 2.
5. Click Configure IdP to open the IdP settings page. You'll return to this page in Step 3 to finalize your Wristband configuration.

---

Step 2: Configure Your Customer's Identity Provider

In this step, the Customer IdP Admin creates a SAML 2.0 application in their identity provider using the SP Entity ID and ACS URL obtained in Step 1. They also configure the attribute and group mappings.

Once the configuration is complete, the Customer IdP Admin must provide the following details to the Wristband Admin to finalize the integration in Step 3:

• IdP metadata: The Metadata URL or SAML metadata XML file, which contains the Entity ID, SSO URL, and Signing Certificate. If neither option is available, these values must be provided individually.
• Attribute names
• Group names (Optional)

2.1: Create the SAML Application

1. Log into your Okta Admin dashboard and perform the following actions:
   • Navigate to Applications and Resources > Applications in the side navigation.
   • Click the Create App Integration button.

2. This will open the Create App Integration modal.
   • Select SAML 2.0 as the sign-in method.
   • Click the Next button.

3. This opens the Create SAML Integration wizard. On the General Settings tab, fill in the following:
   • App name: Any appropriate name for the integration.
   • App logo: (Optional) Used as the application icon displayed to users in the Okta dashboard.
   • App visibility: Leave unchecked unless you want to hide the application icon from users in the Okta dashboard.
4. Click the Next button.

5. Under the Configure SAML tab, fill in the following fields under the SAML Settings section:
   • Single sign-on URL (ACS URL): Paste the ACS URL from Step 1. Leave Use this for Recipient URL and Destination URL checked.
   • Audience URI (SP Entity ID): Paste the SP Entity ID from Step 1.
   • Default RelayState: Leave blank.
   • Name ID format: Select EmailAddress.
   • Application username: Select Email.
   • Update application username on: Leave as Create and update.
6. Click the Next button.

7. The Feedback section is entirely optional. Click Finish to skip this part. Your Okta SAML app is now created and you will be taken to the app's Sign On tab.

8. From the Sign On tab, copy the Metadata URL under the Metadata details section. You will need it to complete Step 3.

2.2: Configure SAML Attributes

When configuring your IdP, you'll need to specify which attributes to include in the SAML response. Wristband reads these attributes during login and uses them to automatically populate the corresponding user attributes.

The following Wristband user attributes can be populated from the SAML assertion:

• id
• email
• emailVerified
• givenName
• familyName
• fullName
• phoneNumber
• birthdate
• groups

The following steps demonstrate how to configure these SAML attributes in an Okta SAML application. The same principles apply to other SAML 2.0-compliant IdPs, though the configuration steps may differ.

1. To create attribute mappings in Okta, navigate to the Sign On tab and scroll to the Attribute Statements section. Click the Add expression button for each attribute you want to include in the SAML response.

2. In the Add expression modal, fill in the following:
   • Name: The name of the attribute (e.g., email, etc.).
   • Expression: The Okta Expression that will be used to derive the attribute value (e.g., user.profile.email).
3. Click Save to store that mapping.

4. Repeat for each attribute you want to include in the SAML response. Common attributes to include are:

5. Copy the attribute names of your configured attribute statements as you will need them in Step 3 to configure the Wristband attribute mappings.

2.3: Configure the Groups Attribute

To use Wristband's Role Mapping feature, which automatically assigns application roles based on a user's IdP group memberships, configure a multi-valued groups attribute in the SAML assertion that contains the user's group identifiers (e.g., group names).

The below instructions show how to add the groups attribute in Okta.

1. In Okta, on the Sign On tab of your application, scroll to the Attribute Statements section and click the Add expression button.

2. In the Add expression modal, fill in the following:
   • Name: groups
   • Expression: user.getGroups({'group.type': {'OKTA_GROUP'}}).![profile.name]. This returns an array of native Okta group objects the user belongs to, then extracts just the name of each group. You will later configure Wristband's role mapping to control which of these groups actually map to roles in your application.
3. Click Save to store that expression.

4. For any Okta groups that should map to roles in the Wristband application, make sure to copy their exact names as you will need them in Step 3 to configure the role mappings. You can find them by navigating to Directory > Groups in the Okta Admin Console.

---

Step 3: Complete the Wristband Configuration

In this step, the Wristband Admin will complete the integration using the metadata and configuration details provided by the Customer IdP Admin in Step 2.

3.1: Provide Your IdP Metadata to Wristband

Navigate back to the Wristband IdP Settings Page where you left off in Step 1. You can provide your IdP's metadata using one of three available options, depending on your provider's capabilities:

• Metadata URL Sync (follow this approach for the Okta example in this guide)
• Metadata XML Upload
• Manual Form Entry

Option A: Metadata URL Sync

1. To fetch the SAML configuration directly from the customer's IdP metadata URL, click the Sync button.

2. In the modal, provide the metadata URL and click Sync.

3. All form fields and signing certificates should now be populated under the IdP Settings section.

Option B: Metadata XML Upload

1. To upload a SAML metadata XML file, click the Upload button.

2. In the modal, click Choose File to provide a SAML metadata .xml file downloaded from your customer's IdP and click Update.

3. All form fields and signing certificates should now be populated under the IdP Settings section.

Option C: Manual Form Entry

For any IdPs that don't provide either a metadata URL or a metadata XML file, you can manually enter the customer's IdP metadata values.

1. Scroll to the bottom of the IdP Settings section. Enter the following values and click Save:
   • Entity ID: The customer IdP's unique identifier.
   • SSO URL: The URL that the customer's IdP uses to initiate SSO requests.

2. Next, scroll down to the Signing Certificates section and click Add Certificate.

3. In the modal, you can either click Choose File to upload the IdP's X.509 signing certificate, or alternatively you can manually paste the value in the form field at the bottom.
4. Click Add to save the certificate. All SAML metadata has now successfully been provided to Wristband.

3.2: Enable and Configure Optional IdP Settings

1. Enable the Identity Provider to allow user authentication through this IdP. If this toggle is greyed out, ensure you have already filled in the following required fields: Entity ID, SSO URL, and Signing Certificate.

2. Additionally, the following IdP Settings are available:

   • Allow IdP-initiated SSO: Enable this if you want users to be able to initiate login directly from your customer's IdP dashboard (e.g., Okta App dashboard).
   • Verified Email Domains: Add the email domains associated with this IdP (e.g., acme.com). When a user authenticates via this IdP, Wristband will automatically mark their email as verified if their email domain matches one of the domains in this list. If the user's email domain does not appear in this list, then Wristband will ask the user to verify their email when they log in under the following conditions:
     • The first time the user is provisioned, if JIT provisioning is enabled.
     • If the user's email changes and the email attribute has attribute syncing enabled.

3. Click Save to apply the changes.

3.3: Configure User Syncing

Navigate down on the IdP Settings page to the User Syncing section. This section features three parts that work together to manage how user attributes from your customer's IdP are handled in Wristband:

• Just-In-Time (JIT) Provisioning
• Attribute Mapping
• Attribute Syncing

Just-In-Time (JIT) Provisioning

1. Enable JIT Provisioning if you want Wristband to automatically provision a user upon a user's first login via this IdP.

IdP Attribute Mapping

Map your customer's IdP attributes (Source Attribute) to the corresponding Wristband user attributes (Destination Attribute). Source attribute names must exactly match the attribute names configured in Step 2.

1. For each attribute you want to map:
   • Click the + Add Mapping button.

2. In the Create IdP Attribute Mapping modal that appears, enter the following information:
   • IdP Attribute (Source): The exact name of the attribute as it appears in the SAML assertion.
   • Wristband Attribute (Destination): Select the Wristband user attribute that the IdP attribute should be mapped to.
3. Click Create to save the attribute mapping.

User Attribute Syncing

Attribute syncing lets you select which Wristband user attributes are automatically updated from your customer's IdP attributes each time a user logs in.

Note: Each Wristband user attribute you want to sync must have a corresponding attribute mapping configured; otherwise, the value of the attribute being synced will always be empty.

1. Specify the Wristband user attributes to sync from the User Attributes to Sync on Login dropdown and click Save.

3.4: Configure Role Mapping

Role mapping allows you to automatically assign roles to a user based on their IdP group memberships.

Before you begin creating role mappings, you must first create an attribute mapping for the Wristband groups attribute.

1. Navigate to the User Syncing section and click the Add Mapping button.

2. In the Create IdP Attribute Mapping modal, provide the following values:
   • IdP Attribute (Source): The name of the groups claim from the SAML assertion. If you've been following the Okta examples, the claim should be called groups.
   • Wristband Attribute (Destination): Select groups from the dropdown.
3. Click Create to persist the attribute mapping.

4. Now that the groups attribute has been mapped to the correct SAML claim, navigate to the Role Mapping section and turn on the Role Mapping toggle.
5. Click the Add Mapping button to create a role mapping.

6. When the Create IdP Role Mapping modal appears, provide the following values:
   • IdP Group Name: Enter the exact group name from the customer's IdP.
   • Wristband Role: Choose the appropriate role from the dropdown menu.
7. Click Create to save the role mapping.

8. Repeat for each group that should map to a role in your application.

3.5: Customize the Login Button

1. To modify the appearance of the SSO login button displayed on Wristband-hosted login pages, click the Customize button.

2. When the Customize Your Custom IdP modal opens, you will see a live preview of the user-facing login button. Fill in the following fields to customize its appearance:
   • Display Name: The text shown on the login button.
   • Logo URL: A publicly accessible URL for the logo displayed on the button. SVG format is recommended; the logo will render at 20x20 px.
3. Click Save to apply your changes.

3.6: Enable Tenant Overrides for IdP

In the Wristband dashboard, enable the identity provider overrides for your tenant.

• Select Identity Providers from the left navigation menu.
• Enable the toggle next to Enable this tenant override.

The Custom SAML SSO integration is now complete. Your users can now navigate to the Tenant-level Login Page to authenticate using the new SSO login button.

---

---

---