This guide covers how customers can configure SSO with our platform (“Mo”) using custom SAML, with specific advice if your identity provider is Google Workspace (G Suite), Microsoft Entra ID (Azure AD) or Okta.
Overview & Assumptions
Before you begin, here are some assumptions and clarifications:
We assume “Mo” is your Service Provider (SP). You will configure your identity provider (IdP) to trust Mo.
You must have administrative access in your IdP (Google Workspace super-admin, Microsoft Entra / Azure AD admin, or Okta admin with application management permissions).
Users in your directory must have the required attributes (email, forename / first name, surname, and a unique identifier, either email or employee ID) available and properly populated.
Your SP (Mo) expects certain URLs and metadata formats (see below). If they change, coordinate with our Mo implementation contact.
Please Note: SSO configuration for Mo is managed by an implementation coordinator at Mo. Before beginning the setup steps in this guide, contact Mo to identify your implementation coordinator and arrange to provide your IdP metadata and short name for configuration.
Guide: Setting Up “Mo” as a SAML SP
Below are the steps. Steps 1-5 are generic, followed by special sections for Google Workspace, Microsoft Entra ID, and Okta to help with their UI peculiarities, attribute/claim mapping, etc.
Step 1: Configure Mo in Your IdP (Set “Mo” up as a SAML Application)
Create a new custom SAML (or enterprise) application in your IdP. The app name might be “Mo” or “<Your Company> - Mo SSO”.
In the “Service Provider / SP / Application Details” you will need to enter:
Entity ID (SAML audience):
<https://api.thanksbox.co/saml/><short-name>/metadata
Where
<short-name>is your company’s short name (must be in lower case).ACS (Assertion Consumer Service) URL (also called Consume Link, Consumer URL):
<https://api.thanksbox.co/saml/><short-name>/consume
(Optional) RelayState / Start URL if you want users to be redirected to a particular page after login.
Name ID / Name Identifier Format: usually Email or UserPrincipalName, depending on the IdP.
Upload or exchange metadata if needed: the SP metadata and/or certificates, depending on whether your IdP can import metadata or you need to set fields manually.
Step 2: Define Required User Attributes / Claims
We require the following attributes in the SAML assertion:
Attribute | Purpose / Use | Requirement / Note |
SSO-UID (unique identifier) | Used to match assertions to existing Mo user accounts | Must be either: Employee ID number OR Email address (or UPN). If using email/UPN, must be lower-cased because Mo treats SSO-UID as case-sensitive. |
Email address | For login & communications | Standard attribute; must match what’s in Mo’s user record. |
Forename / First name | Display & identification | Standard attribute. |
Surname / Last name | Display & identification | Standard attribute. |
You may rename the attributes in your IdP as long as you notify us (Mo) of the exact name/claim URIs so we can map them correctly.
Ensure other fields such as NameID match the same value you choose for SSO-UID if email or UPN is used.
Step 3: Provide Metadata & Certificates
Once you’ve set up the Mo app in your IdP, send us the IdP metadata in XML format. This should include:
IdP login (Single Sign-On) URL (where Mo sends users to authenticate).
IdP entity ID / Issuer.
Name Identifier Format (e.g.
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddressor another agreed format).Signature / digest algorithms (e.g. SHA-256).
Public certificate(s) used to sign or optionally encrypt assertions.
The attribute / claim names matching the required attributes above.
We will review the metadata and configure Mo to trust your IdP.
Step 4: Mo Configures Its Side
Once we receive the metadata and validate it, we will:
Add your IdP as a trusted provider in Mo.
Enable the ACS / Entity ID endpoints (the ones from Step 1) to go live.
Ensure our side has matching attribute mapping settings so login assertions match correctly.
We will typically confirm readiness for testing within 3-5 working days of receiving valid metadata.
Step 5: Testing
Testing is essential. Please perform the following:
Test with at least two user accounts:
Your own account.
Another test account (which we may also create on our side) to verify typical user behaviour.
Test the following scenarios:
SP-initiated login: User clicks Mo’s login link / enters via Mo portal (e.g.
my.mo.work) → redirected to IdP → returns to Mo.IdP-initiated login: User starts from your IdP portal / application launcher → selects Mo → logs in.
Account suspension / disable: If user is disabled in your directory, login must fail.
Mobile app access: Both Android & iOS, on work or personal devices.
Verify attribute values:
The SSO-UID matches exactly to Mo’s user record.
First name, surname, email are correctly populated.
Assertion is signed / encrypted if Mo requires, and digest/signature methods are supported.
Certificate rollover (if your certificates expire regularly), you may optionally test new certs ahead of expiry.
Detailed Provider Setup Guides
Google Workspace-Specific Instructions
Google Workspace-Specific Instructions
Here are details for Google Workspace (G Suite) IdP.
Step | Notes / Particulars |
Creating the custom SAML app | Sign in to the Google Admin console as a super-administrator → go to Apps → Web and mobile apps → Add app → Add custom SAML app. Google Help |
IdP metadata | Google gives you the SSO URL, Entity ID, and certificate; optionally you can download full metadata XML. Google Help |
Service Provider (SP) Details | In Google’s workflow, when entering the SP details for Mo, you will need to enter the ACS URL and Entity ID exactly as provided above. Also set the Name ID format to email (or UPN if using that). Be careful: sometimes Google allows Name ID formats unspecified, which may not match what Mo expects. |
Attribute mapping | You can map attributes/custom attributes (forenames, surnames, employee ID) via “Attribute Mapping” step in the SAML app configuration in Google Workspace. Make sure these are enabled. Google Help |
Turning on the app / user access | Once configured, enable user access for the app (either for all or specific OU groups). Changes may take time to propagate. Google Help+1 |
Microsoft Entra / Azure AD-Specific Instruction
Microsoft Entra / Azure AD-Specific Instruction
For organisations using Microsoft Entra ID / Azure Active Directory, here are steps and important notes.
Step | Notes / Particulars |
Registering / Creating the application | In Azure portal, go to Enterprise Applications → New application → Create your own application (or sometimes “+ New SAML application”) → give it a name. Ory Corp+1 |
Basic SAML Configuration | Under that application, open Single sign-on → SAML. Then edit the Basic SAML Configuration to set: • Identifier / Entity ID = |
Attributes & Claims | Azure AD allows you to edit “Attributes & Claims” after enabling SAML. By default, Azure issues claims like |
Optional / Additional Claims | If Mo requires specific optional claims, Azure supports optional claims and group claims etc. You can configure via: Token configuration or via editing the manifest. Microsoft Learn+1 |
Metadata / Certificate | From Azure: you can download the federation metadata XML for the application (which includes the signing certificate). Send that metadata to us. Ory Corp+1 |
Okta- Specific Instructions
Okta- Specific Instructions
For organisations using Okta as their identity provider, here are detailed steps and important notes.
Initial Setup
Creating the custom SAML app
Sign in to the Okta Admin Console → go to Applications → Applications → Create App Integration → Select SAML 2.0 → Click Next. Name your app "Mo" or "<Your Company> - Mo SSO". Okta Help
General Settings
App name: Mo (or your preferred name)
App logo: (Optional) Upload Mo logo
App visibility: Check "Do not display application icon to users" if you want to hide from Okta dashboard
Click Next
Configure SAML
Enter the following SP details:
Single sign on URL:
https://api.thanksbox.co/saml/<short-name>/consumeUse this for Recipient URL and Destination URL: ✓ Check this
Audience URI (SP Entity ID):
https://api.thanksbox.co/saml/<short-name>/metadataDefault RelayState: (Leave blank unless Mo specifies)
Name ID format: EmailAddress
Application username: Email
Update application username on: Create and update
Attribute Statements
Add these required mappings (case-sensitive):
Name → Value
SSO-UID→String.toLowerCase(user.email)ORuser.employeeNumberEmail→user.emailForename→user.firstNameSurname→user.lastName
⚠️ Note: The lowercase transformation for SSO-UID is critical if using email
SAML Settings Preview
Review your settings before clicking Next. Ensure all URLs use your correct <short-name> value
Feedback
Select "I'm an Okta customer adding an internal app" → Finish
Post-Creation Configuration
Download Metadata
Sign On tab → Metadata section → Metadata URL (copy this) or Actions → View IdP metadata → Save the XML file. Send this metadata to Mo support.
View Setup Instructions
Sign On tab → View SAML setup instructions provides:
Identity Provider Single Sign-On URL
Identity Provider Issuer
X.509 Certificate
Advanced Sign On Settings
Click Edit in Sign On tab → Advanced Sign On Settings:
Response: Signed
Assertion Signature: Signed
Signature Algorithm: RSA-SHA256
Digest Algorithm: SHA256
Assertion Encryption: Unencrypted
SAML Single Logout: Disabled
Honor Force Authentication: Yes
SAML Issuer ID: Use default
User Assignment
Assignments tab → Assign → Choose:
Assign to People: Individual users
Assign to Groups: Entire groups (recommended)
Testing Configuration
SP-initiated SSO
Log out of Okta completely
Navigate to Mo's login page https://my.mo.work/
Click SSO/Enterprise login
Should redirect to Okta → authenticate → return to Mo
IdP-initiated SSO
Log into Okta dashboard
Click the Mo application tile
Should directly log into Mo without re-authentication
Attribute Validation
Reports → System Log → Find SAML login event → Debug shows full SAML assertion with attributes
Failed Login Debugging
Check System Log for errors:
"User not assigned" = Assignment issue
"Attribute statement not found" = Attribute mapping issue
"Invalid signature" = Certificate mismatch
Okta-Specific Troubleshooting
Case Sensitivity Problems
Ensure SSO-UID uses String.toLowerCase(user.email) expression if email-based. Mo treats SSO-UID as case-sensitive.
Missing Attributes
Verify user profile has all required fields populated in Okta. Go to Directory → People → Select user → Check profile completeness
Certificate Expiry
Okta rotates certificates automatically. Check Sign On tab for next rotation date.
Users Can't See App
Check:
User/group assignment
App visibility settings
User's Okta dashboard configuration
Intermittent Failures
Check if using Okta Classic vs. Okta Identity Engine (OIE). Some SAML behaviours differ between versions.
Okta Support Resources
Okta Support: Available through Admin Console → Help → Contact Support
Next Steps
Send the following to your implementation coordinator:
Confirmation of Your Short Name
Your implementation coordinator will need confirmation of your organisation's unique short name. This should ideally be your company name and must be in lowercase (e.g., "acmecorp" or "globaltech").
Your IdP Metadata
After configuring Mo as a SAML application in your identity provider (following Steps 1-3 in this guide), provide your IdP metadata XML file to your implementation coordinator. This file contains:
IdP Single Sign-On URL
IdP Entity ID/Issuer
Public certificate(s)
Attribute/claim mappings
What Happens Next:
Mo Configuration
Your implementation coordinator will configure Mo's side of the SSO integration, typically within 3-5 working days of receiving valid metadata.
Coordinated Testing
Once both sides are configured, your implementation coordinator will confirm and then arrange testing with you to verify the integration works correctly.