Configure SAML authentication for enrollments with Okta

This guide provides instructions to configure SAML authentication for enrollments in SimpleMDM using Okta as the identity provider. SAML authentication for enrollments provides a layer of security to ensure that only users from your organization can enroll devices into MDM. It also allows admins to map attributes from Okta to custom attributes in SimpleMDM, which can be useful for capturing information about the user for other users, such as configuration profiles, dynamic groups, and more.

Please note, Okta's interface may change over time and all steps/actions may not be exact, but general concepts should be the same.

First, sign in to SimpleMDM and navigate to the enrollment you want to configure SAML authentication for. Note: Once a SAML authentication provider has been configured, this can be re-used for other enrollments.

Configuring the SAML settings for Okta and SimpleMDM

1. In SimpleMDM, navigate to the Enrollments page.
2. Click the Enrollment that you want to configure authentication for.
3. Click the "Authentication" tab of the enrollment.
4. Click the dropdown and select "New Enrollment Authentication".
5. Give the authentication a name. Once saved, this is the name that will be displayed in the dropdown if you want to use it for other enrollments.
6. The Consumer URL and SAML audience values will be pre-filled. These will need to be copied and entered on the Okta side in following steps. Keep this page open and open Okta in a separate tab/window.
7. Sign in to your Okta account as an admin.
8. In Okta, navigate to the Applications > Applications section of the navigation menu.
9. Click "Create App Integration".
10. In the "Create a new app integration" dialog, select "SAML 2.0" as the sign-in method and click "Next".
11. Give the app integration a name that makes it clear what it's purpose is (ex. "SimpleMDM enrollment authentication"). Optionally fill out other settings and click "Next".
12. In SimpleMDM, copy the full value in the "Consumer URL" field, switch back to the Okta tab and paste this value into the "Single sign-on URL" field in the Okta SAML settings.
13. In SimpleMDM, copy the full value in the "SAML Audience" field, switch back to the Okta tab and paste this value in the "Audience URI (SP Entity ID)" field in the Okta SAML settings.
14. In Okta, all other fields in the Okta SAML settings can be left as-is. Click "Next" and continue until finished/saved.
15. Once saved, Okta should display a "Metadata details" section. Click "More details" to expand the list of information to expose the "Sign on URL".
16. Copy the "Sign on URL" from Okta and paste it into the "SAML target URL" field in SimpleMDM.
17. In Okta, click the Download button next to the "Signing Certificate" field. This will download a file named like Okta.cert.
18. Open the Okta.cert file in a text editor application like TextEdit.app and copy the full value of the certificate.
19. Paste this value into the "X.509 fingerprint or certificate" field in SimpleMDM.
20. Save the SimpleMDM authentication settings.
21. In Okta, assign users to the SimpleMDM auth application. This can be done under the "Assignments" tab for the application in the Okta interface. 

Testing the SAML authentication integration

1. To test the integration, make sure you assign an Okta user that you have the credentials for.
2. Back in the SimpleMDM authentication settings, click "Test Current Configuration". This will launch an Okta authentication flow. Sign in with your Okta credentials to test it.
3. If you are already signed in to your Okta account as the same user in the same browser, you will likely see an "Authentication Successful" screen. This test flow will log you out of SimpleMDM, so you may need to sign back in.
4. You can optionally test this authentication integration again by copy and pasting the "Consumer URL" from SimpleMDM into a private browser window. This should trigger an Okta authentication flow.

For best results, we recommend testing this full flow by enrolling a test device before enabling for your production environment.

Configure attribute sync from Okta to SimpleMDM custom attributes

When using SAML auth for enrollments, admins can optionally have user data sync from Okta to SimpleMDM custom attributes to capture more information about the user. These steps explain how to configure this.

1. Open the SAML application settings in Okta again.
2. Click the "Sign On" tab.
3. Scroll down to the "Attribute statements" section.
4. To sync user profile attributes, user the "Profile attribute statements" section. For example, set Name to "firstName" and Value to "user.firstName".
5. In SimpleMDM, go to Configs > Attributes and create custom attributes that match the Okta attributes. For example, create a SimpleMDM custom attribute named "firstName".

6. Once the attributes have been configured on both the Okta and the SimpleMDM side, test the authentication again from the SimpleMDM enrollment authentication settings page. If configured correctly, you should see page like this after authenticating:

   

   Note: Refer to Okta's documentation for the latest guides and information on configuring Okta attributes.