Skip to content
English
Sign in
Contact us
  • There are no suggestions because the search field is empty.

How do I set up SAML and SCIM for Okta?

This guide walks you through connecting Moxso to Okta using SAML (single sign-on) and SCIM (automated user provisioning). You'll set up both in a single Okta app integration.

SAML lets your admins and employees log into Moxso using their Okta credentials. No separate Moxso password required.

SCIM keeps your Moxso users and groups in sync with Okta automatically. When someone joins, changes department, or leaves your organization, Okta pushes those changes to Moxso without any manual work.

Enabling SCIM makes user and group management in Moxso read-only. Once SCIM is active, you can no longer add or edit users manually, and you can no longer manage groups directly in Moxso. All user and group management must happen in Okta. Make sure your Okta directory is accurate before you enable SCIM.

How it works

The setup has two parts that build on each other. SAML handles authentication (how admins and employees log in) and SCIM handles provisioning (how users and groups stay up to date). Both are configured within the same Okta app.

Before you begin

Check the following before starting:

  • Your organization's domains are verified in Moxso. Go to Settings and check the Verified domains section. Domains must show a Verified status. Moxso only syncs users whose email addresses match a verified domain.
  • You've decided which Okta users or groups to sync. We recommend starting with a small test group to verify the setup before rolling it out to everyone.

Part 1: Set up SAML

Step 1: Start the SAML provider setup in Moxso

  1. In Moxso, go to Settings > SAML single sign-on.
  2. Click Add provider.
  3. Under Require SAML for, select Admin users.
  4. Enter a Name for the provider, for example Okta.
  5. Set Provider to Okta.
  6. Scroll down to SAML configuration.

 

Okta Saml Setup Initial Screen

Copy the following values. You'll need them in the next step:

Value

Where it goes in Okta

ACS URL

Single sign-on URL

Metadata URL

Audience URI (SP Entity ID)

Leave the form open. You'll return to it shortly.

Step 2: Create the Moxso app in Okta

OKTA Create App

  1. In Okta, go to Applications > Applications.
  2. Click Create App Integration.
  3. Select SAML 2.0 and click Next.
  4. Enter an App name, for example Moxso. Click Next.
  5. On the Configure SAML screen, enter the following:
    • Single sign-on URL: paste the ACS URL from Moxso.
    • Audience URI (SP Entity ID): paste the Metadata URL from Moxso.
    • Leave Use this for Recipient URL and Destination URL checked.
    • Leave Name ID format as Unspecified.
  6. Click Next, then Finish.

Okta creates the app and opens it on the General tab.

Step 3: Enable SCIM provisioning in the Okta app

While you're on the General tab:

  1. Click Edit in the App Settings section.
  2. Under Provisioning, select SCIM.
  3. Click Save.

This unlocks the Provisioning tab, which you'll configure in Part 2.

Step 4: Get your setup values from Okta

Now Okta needs to give Moxso the values to complete the SAML connection.

  1. In the Moxso app in Okta, go to the Sign On tab.
  2. Under Metadata details, copy the Metadata URL.

Using the metadata URL is the recommended method. Moxso fetches the IdP entity ID, login URL, and certificate automatically, which reduces the chance of configuration errors.

If you prefer to complete the setup manually, copy the following values:

Value

Where it goes in Moxso

Issuer

IdP entity ID

Sign on URL

IdP login URL

Sign out URL

IdP logout URL

Signing Certificate

IdP X.509 certificate (download or copy)

OKTA SAML Values

Step 5: Complete the SAML setup in Moxso

  1. Go back to the Add provider form you opened in step 1.
  2. Scroll down to Create from metadata URL.
  3. Paste the Metadata URL from Okta into the App federation metadata URL field.
  4. Click Fetch metadata.
  5. Toggle Enable provider on.
  6. Click Save provider.
     

We recommend keeping SAML Single Logout disabled in Okta (it's off by default). If enabled, signing out of Moxso signs the admin out of all other applications they're logged into through Okta. This is rarely the intended behavior. Leave it disabled unless you have a specific reason to turn it on.

    Step 6: Test the SAML login

    Before moving to SCIM, verify the SAML connection works.

    1. Open a private browser window.
    2. Go to your Moxso admin login page.
    3. Select the Okta provider you just created.
    4. Log in with an Okta admin account.

    If the login succeeds, SAML is working. If it fails, go back and check that the values in Moxso and Okta match exactly.

    To set up SSO for employees (Hub users in Moxso), repeat steps 1 to 6 and select Hub users instead of Admin users in step 1.

    Part 2: Set up SCIM

    Step 7: Create a SCIM connection in Moxso

    1. In Moxso, go to Settings > SCIM connections.
    2. Click Create connection.
    3. Enter a Connection name, for example Okta.
    4. Set Provider to Okta.
    5. Turn Enabled on.
    6. Click Save connection.

    The Provisioning endpoint section now shows your Tenant URL: https://api.moxso.com/scim/v2

    Keep this page open.

    Step 8: Generate a SCIM token

    Okta needs a token to authenticate with Moxso.

    1. Scroll down to the SCIM provisioning tokens section on the same page.
    2. Click Create token.
    3. Enter a token name, for example Okta provisioning.
    4. Click Create token.

    Moxso SCIM Create Token

    A SCIM token created dialog appears with your secret token.

    Copy this token now. It's only shown once. If you close this dialog without copying the token, you'll need to delete it and create a new one.

    Copy the token and store it somewhere you can access in the next step.

    Step 9: Configure SCIM in Okta

    1. In the Moxso app in Okta, go to the Provisioning tab.
    2. Click Integration in the left pane > Edit.
    3. Fill in the SCIM Connection form with the following values:
      • SCIM connector base URL: https://api.moxso.com/scim/v2
      • Unique identifier field for users: email
      • Supported provisioning actions: select Import New Users and Profile Updates, Push New Users, Push Profile Updates, and Push Groups.
      • Authentication Mode: select HTTP Header.
    4. In the Authorization field that appears, enter your token in this format: Bearer <your-token>, replacing <your-token> with the token you copied in step 8.
    5. Click Save.

    Okta SCIM Setup

    Step 10: Enable provisioning features

    1. In the Provisioning tab, select To App in the left panel.
    2. Click Edit on the right side of the Provisioning to App section.
    3. Enable the following features:

      Feature

      What it does

      Create users

      Creates a Moxso account when you assign a user to the app in Okta.

      Update user attributes

      Syncs attribute changes from Okta to Moxso automatically.

      Deactivate users

      Deactivates the Moxso account when a user is unassigned or deactivated in Okta.
    4. Leave Sync Password disabled.
    5. Click Save.

    We recommend enabling all three features. If you skip Deactivate users, former employees will keep their Moxso access after leaving your organization.

    Step 11: Check attribute mappings

    The attribute mapping table below shows the default mappings. You don't need to change these unless your Okta profile uses non-standard attribute names.

    Moxso field

    Okta attribute

    First name

    name.givenName

    Last name

    name.familyName

    Email

    emails[type eq "work"].value

    Department

    urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department

    Locale

    user.preferredLanguage

    Manager

    urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager

    Phone number

    phoneNumbers[type eq "work"].value

    Timezone

    timezone

    To view or change mappings, go to Provisioning > To App > Attribute Mappings in Okta.

    Moxso only processes attributes it actively supports. Additional attributes sent from Okta are ignored. If you're unsure which attributes to keep, click Reset to defaults in the Moxso SCIM connection settings.

    Step 12: Assign users or groups in Okta

    1. In the Moxso app in Okta, go to the Assignments tab.
    2. Click Assign and select Assign to people or Assign to groups.
    3. Select the users or groups you want to sync and click Assign for each.
    4. Click Done.

    For your first sync, assign a small test group. Two or three users is enough. Verify they appear correctly in Moxso before assigning everyone.


    Step 13: Trigger your first sync

    1. In the Moxso app in Okta, go to the Provisioning tab.
    2. Click Force Sync to start the first sync immediately.

    The sync runs in the background. Once complete, go to User management in Moxso to confirm your test users appear with the correct attributes.

    Sync schedule

    After the first sync, Okta pushes changes to Moxso automatically. The frequency depends on your Okta plan, typically every 40 minutes. You can trigger a manual sync at any time using Force Sync in the Okta app.

    Common questions

    What happens to existing Moxso users when I first enable SCIM?
    Users whose email addresses match users in Okta are linked automatically. Users who exist in Moxso but not in Okta remain as-is until you deactivate or remove them manually. Once SCIM is enabled you'll need to manage that from Okta.

    Can I use SAML without SCIM?
    Yes. SAML for admin login and SCIM for provisioning are independent. You can set up SAML alone if you want single sign-on without automated user sync.

    What happens if I disable the SCIM connection?
    Disabling the SCIM connection restores manual user and group management in Moxso. Existing users are not removed. Future changes in Okta will no longer sync until you re-enable it.

    A user changed their department in Okta. Does that update in Moxso?
    Yes, if Update user attributes is enabled in Okta. The change syncs on the next automatic or manual sync.

    Can I prevent specific users from being managed by SCIM?
    Not at the individual user level. SCIM manages all users assigned to the Moxso app in Okta. To exclude a user, remove them from the app assignment in Okta.