How to configure Single-Sign-On between Mosaic and Okta

In this article you will find the necessary steps to configure a connection between Okta and Mosaic's authentication platform to establish a Single-Sign-On experience for your enterprise users using Mosaic.

If at any time there are questions or issues with the connection, please reach out to support@mosaic.pe for assistance.

Okta Configuration

1. In the Okta Developer Console, choose Applications > Applications > Create App Integration. Choose SAML 2.0 as the Sign-in method.
2. Enter “Mosaic” for the app name, and you can use the this logo (or the one attached below) if desired for the directory listing.
3. Under General, for the Single Sign On URL, use https://auth.mosaic.pe/saml2/idpresponse
4. For Audience URI / SP Entity ID, use urn:amazon:cognito:sp:us-east-1_snwpaAR4h
5. For Name ID Format, choose Email Address
6. Under Attribute Statements, use the following Name/Value combinations:
   1. Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
      Value: user.email
   2. Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
      Value: user.firstName
   3. Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
      Value: user.lastName
7. On the Assignments tab, choose Assign to People and assign your local users permission to Mosaic accordingly.
8. On the Sign On tab, find the Identity Provider Metadata hyperlink and either copy/paste that URL to us, or save the file at the resulting URL and email to support@mosaic.pe.

Note: If you are utilizing the directory listing, you will need to create a separate bookmark link to https://app.mosaic.pe/login/<your primary domain> and hide the authorization entry from the directory. Otherwise, users attempting to log in via the directory listing may receive and Invalid samlResponse or relayState from identity provider.  See Okta's documentation for additional context.

Mosaic Configuration

Once you have completed the steps above, please email support@mosaic.pe with the metadata from Step 7, as well as a list of all possible domains that might be authenticating via your Okta instance.  For example: yourdomain.com, yourdomain.net, etc.

SSO User Provisioning

Mosaic supports user provisioning to enable Okta to automatically create and disable user accounts within Mosaic depending on their application access.  We recommend following the additional steps to enable this functionality.  Note this can only be completed once SSO has been successfully established for your organization.

1. Obtain your Provisioning Token

1. Login to Mosaic as a user with admin permissions.
2. Navigate to your organization admin page by clicking on your account name in the top right corner, and selecting "Admin"
3. Navigate to the "Integrations" page using the left sidebar
4. Find the SCIM User Provisioning integration, and click "Install", and then "Generate Token".
5. Copy the Base URL and API Token
   Note: The token is only visible once and is valid for 365 days.  Creating a new token will invalidate the previously used token.

2. Enable SSO User Provisioning in Okta

1. Login to Okta and find the Mosaic application
2. Click Provisioning
3. Click Configure API Integration
4. Set the Unique Identifier Field for Users to userName
5. Ensure the Authentication Mode is HTTP Header
6. Enable the API Integration and paste the Base URL and API Token from above.
7. Click Test API Credentials
8. Click Save once the credentials are tested successfully.
9. Click the "To App" tab and click Edit
10. Select the checkboxes for Create Users, Update User Attributes, and Deactivate Users, then click Save.
11. Click the "To Okta" tab and click "Edit" under the User Creation & Matching section
12. In the Imported user is an exact match to Okta user if section, select Email Matches
13. Click Save
14. If you have previously assigned users to the application, you may need to force sync to initialize the provisioning connection.