The single sign-on (SSO) capability in Device Magic allows you to leverage an identity provider like Okta to handle user authentication, user provisioning, and device provisioning for Device Magic.
Set up in Okta
To setup Okta for user provisioning, you will need to follow these steps:
1. From the Okta Admin console, create a new application integration
2. Select SAML 2.0
3. Provide an App name (and optionally a logo)
4. Set the General settings as follows:
Single sign on URL (need to provide two - one for login via a web browser and one for mobile app login):
web: https://app.devicemagic.com/users/saml/auth
mobile app: https://mobileforms.devicemagic.com/users/saml/device_auth
Note: The mobile app SSO URL can be provided by selecting the checkbox for "Allow this app to request other SSO URLs" and entering the URL there.Audience URI (SP Entity ID): https://app.devicemagic.com/users/saml/metadata
5. Setup the Attribute Statements to provide the claims that will be sent to Device Magic for user, group, and role information.
For each of these, the Name Format should be set to URI Reference. You can set the Value field to any data fields that you have configured in Okta:
User email address (Required): http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
First Name (Optionally set user name in profile): http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last Name (Optionally set user last name in profile): http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Phone (Optionally set user phone number in profile): http://schemas.xmlsoap.org/ws/2005/05/identity/claims/phone
Groups (Group set when provisioning device): http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
Roles (Role set when provisioning user): http://schemas.xmlsoap.org/ws/2005/05/identity/claims/roles
Note: The values listed above are just examples. You will need to ensure that the values you select are the values that exist in your own Okta deployment that will be what you want to use with Device Magic.
Groups
The value passed in as the "groups" claim (above as user.department) needs to match the value listed in your SAML settings as "Device Group Identifier". This will determine whether or not the device can authenticate.
Roles (required)
The value passed in as the "Roles" claim (above as user.department) needs to match one of the Roles that you have setup in the "Manage Users & Roles" section of Device Magic. This will determine whether the user can authenticate and what role they will be assigned when they do.
6. Click Finish on the last page and then scroll to the bottom of the page to access the SAML Setup section and click on "View SAML setup instructions"
7. On this page you will find your X.509 certificate. Okta does not provide a certificate fingerprint, which is needed for configuring Device Magic, so you will need to use a certificate fingerprinting tool to get the SHA-1 fingerprint of the certificate such as https://www.samltool.com/fingerprint.php.
Paste the X.509 certificate in the tool, select SHA-1, and generate a fingerprint. This value will be used along with the other values listed on the SAML setup instructions page to configure Device Magic. Make note of these settings for use later.
8. At this point you will want to ensure the users that you want to provide access to Device Magic are assigned to this application on the Assignments tab. It is also a good idea to ensure that the values you selected for the claims are also filed out in Okta for those users.
Note: The user does not have to exist in the Device Magic Management console prior to setting up SSO. Logging in with SSO will automatically create them.
Now we will move on to the SAML configuration in Device Magic.
SAML Setup in Device Magic
9. Navigate to the Device Magic SAML page by clicking on Settings > Organization Settings and then clicking the SAML Settings link on the right hand of the page under Integrations.
10. On this page you are going to fill out the fields with the values from step 7 above (the values found in the Okta SAML setup instructions). Click Save and you can now test authentication through Okta.
The Sign-Out URL should be set to take the user back to the SAML login page at:
https://app.devicemagic.com/users/saml/start
or you can redirect the user to a page hosted at your company site if you prefer. For instance, the Okta redirect URL would be:
site.okta.com/app/UserHome?fromAdmin=true
With setup now complete, you can test your setup by logging out of Device Magic and then going to:
https://app.devicemagic.com/users/saml/start
This link can be accessed by clicking "Log in with SSO" from the login page.
Note: When a device signs in using SSO, they will automatically be joined to your organization without an administrator first approving each device. Any SSO devices will be billed at your current subscription rate.
Troubleshooting
If you run into the issue of an "Device Magic Internal Error" when trying to save your SAML settings / logging in, please see below:
Error can occur when there is no role associated with the account. Check that User Roles set up in both Device Magic and Okta are exactly the same.
If you have any questions or comments feel free to send us a message at support@devicemagic.com.