This guide walks through configuring Okta to manage single sign-on and user provisioning for Matik. The Okta integration supports the following functionality:
Single Sign-On (SAML 2.0)
- IdP-initiated SSO: The user logs into Okta (the Identity Provider) first, in order to access Matik (the Service Provider) without re-entering credentials.
- SP-initiated SSO: The user goes directly to Matik (the Service Provider) to log in, and Matik redirects them to Okta (the Identity Provider) to authenticate. After Okta verifies their identity, it sends them back to Matik automatically and logs them in.
Provisioning (SCIM)
You can optionally configure the integration to manage user provisioning using Okta.
- Import Users: Existing Matik users can be imported into Okta and either matched against existing Okta users or created as new Okta users.
- Push Users: Users assigned to the Matik application in Okta are automatically created as end users in your Matik enterprise.
- Update User Attributes: Updates made to the user attributes through Okta will be pushed to Matik.
- Deactivate Users: Deactivating the user or disabling the user's access to Matik through Okta will deactivate the user in Matik.
You can also configure the integration to manage user groups.
- Import Groups: Groups can be imported from Matik into Okta.
- Group Push: Groups and their members in Okta can be pushed to Matik.
For more information on the listed features, visit the Okta Glossary.
Prerequisites
To set up the integration with Okta and Matik, you must have Super Admin or equivalent permissions in Okta and Producer Admin permissions in Matik.
Single Sign-On
Configuring Single Sign-On
To get started, complete these steps in Okta:
-
Add Matik to your Okta instance (Admin Console > Applications > Browse App Catalog > search Matik)
-
Select Matik. (NOTE: Matik (Basic Auth) is the legacy integration. Do not select it for new SSO setup)
-
Click Add Integration.
- On the Sign On tab of the Matik application page, copy the SAML Metadata URL.
Now, in the Matik app:
- In Matik, navigate to enterprise settings and scroll down to the SSO section.
- Select the Use Single Sign On checkbox on the right of the SSO section, and then select Use Okta as an identity provider.
- Enter the SAML Metadata URL value you copied from Okta and your organization's domain.
- Click Update in the bottom right corner to save.
Assigned users can now access Matik via IdP-initiated or SP-initiated SSO.
Note that, at this point, users must still have a Matik account created before they can authenticate via Okta SSO. To automatically provision users that have been assigned individually or by a group from Okta, follow the provisioning steps.
Logging in via Single Sign-On
For IdP-initiated SSO, users can log in from the Okta app:
For SP-initiated SSO, users can log in from Matik. To do so:
- Navigate to Matik's login page: https://app.matik.io/login
- Enter your email address and click Next.
- You'll be redirected to Okta to authenticate.
- After successfully authenticating in Okta, you will be automatically redirected back to Matik and logged in.
Users with the Producer Admin role can either log in with their email and password or click Log In With Okta to use SP-initiated SSO. This ensures Producer Admins retain access if SSO becomes misconfigured.
Provisioning (Optional)
If you would like to use Okta to manage creating and removing Matik accounts, you can set up provisioning.
Enabling Provisioning
To get started, complete the following steps in Okta:
- If you have not done so already, add Matik to your Okta instance (Admin Console > Applications > Browse App Catalog > search Matik), select Matik, and click on Add Integration.
- On the Provisioning tab of the Matik application page, click Configure API Integration and then check the Enable API integration checkbox.
- If Okta is your source of truth for identity, we recommend leaving Import Groups unchecked. If you import groups from Matik, those groups become app-sourced in Okta, and you will only be able to manage the groups from the Matik app.
- Click Authenticate with Matik.
- A Matik authentication prompt will appear. Log in with the producer admin user that will be used to connect to the integration. If you were already logged into the producer admin in Matik, you don't need to log in again.
- Click Grant Access to permit access.
- Click Save.
- Click To App on the left panel, then under Provisioning to App, enable:
- Create Users
- Update User Attributes
- Deactivate Users.
- Click Save. Note that by default, Attribute Mappings are pre-configured and do not need to be changed unless your organization's custom configuration requires it.
Assigning Users via Okta
Once provisioning is setup up, you can assign users to Matik in two ways:
- Individually (Assignments tab > Assign > Assign to People): Creates a Matik user for that person if one doesn't already exist for their email.
- By group (Assignments tab > Assign > Assign to Groups): Creates a Matik user for each group member, if one doesn't already exist for their email.
Either method provisions users into Matik. However, assigning a group to the app does not create a corresponding group in Matik. It only provisions the members as individual users. To also create the group in Matik and keep its membership in sync, follow the steps in Pushing Groups to Matik.
NOTE: If Okta is your source of truth for identity, do not click Import Now on the legacy app's Import tab. This pulls user attributes from Matik into Okta and can overwrite values Okta considers authoritative.
Mirroring Okta Groups in Matik via Group Push (optional)
If you want your Okta groups mirrored as groups in Matik, you can use Group Push. This is helpful if you want to use Okta as your source of truth for managing user groups.
Important: Okta requires two separate groups per team — one for app assignment and one for Group Push. You cannot use the same group for both. See the Okta documentation for more information.
For example, to push a "Sales" team to Matik, you should have two Okta groups:
- matik-app-sales: assigned to the Matik app (provisions users)
- matik-push-sales: pushed to Matik via Group Push (creates the group in Matik)
To keep memberships of these two groups in sync without manual work, set up a group rule:
- In the Admin Console, go to Directory > Groups > Rules and click Add Rule.
- Name the rule (e.g., matik-app-sales).
- Under IF, select Group membership > includes any of the following, and pick matik-app-sales.
- Under THEN Assign to, pick matik-push-sales.
- Save and activate the rule.
Once the rule is active, any user added to matik-app-sales will automatically be added to matik-push-sales as well.
- On the Matik application page, go to the Push Groups tab.
- Click the settings (gear) icon and uncheck Rename app groups to match group name in Okta, then click Save. This lets you give the group a clean name in Matik (e.g., "Sales") instead of the Okta name (e.g., matik-push-sales).
- Click Push Groups > Find groups by name, search for your push groups (e.g. matik-push-sales) to push.
- Select Create Group for the push action, add the group name you want displayed in Matik. Then click Save when you're ready.
Migrating from the Legacy 'Matik (Basic Auth)' App
This section is only relevant if your enterprise is using Matik's legacy Okta App. You can tell if you're using the legacy Matik (Basic Auth) app by checking the name of your Matik SSO App in Okta.
Migrating is only required if you want to leverage the newer group provisioning functionality.
To migrate, start with the following setup:
- Add the new Matik integration to your Okta instance (Admin Console > Applications > Browse App Catalog > search Matik), select Matik, and click on Add Integration.
- Name this 'Matik (New)' or anything else to differentiate from the existing one. Be sure to check Do not display application icon to users to prevent users from accidentally opening the app before the migration is complete, then click on Done.
- Go to the Assignments tab. Click Assign and start assigning the same users and/or groups that are assigned to the legacy instance. Make sure you assign all the users and groups to the new Matik instance to avoid any accidental deprovisioning or loss of access for your users.
Note: If Okta is your source of truth for identity, do not click Import Now on the legacy app's Import tab. This pulls user attributes from Matik into Okta and can overwrite values Okta considers authoritative.
- Follow the provisioning steps.
- On the legacy Matik (Basic Auth) app, go to Provisioning > Integration, click Edit, and uncheck Enable API integration.This stops the legacy integration from making changes without deactivating any users.
Next, you'll need to actually swap to using the new app.
Note: to minimize potential downtime, we recommend doing the following final
steps as quickly as possible, ideally outside of business hours.
(If you need to roll back due to issues, you can re-paste the legacy app's SAML
metadata URL into Matik's enterprise settings, re-active the legacy app, and
re-enable the provisioning actions.)
- Deactivate the Matik (Basic Auth) instance.
- On the Sign On tab of the Matik application page, copy the SAML Metadata URL, and paste it into Matik in the SSO section of enterprise settings.
- Rename the new Matik instance to the legacy instance name, uncheck Do not display application icon to users, and Save.
Comments
0 comments
Article is closed for comments.