What is SSO?
SSO is an authentication and access control technology which allows users to log into multiple applications using a single set of credentials. Using SSO with Opendock provides a better user experience for your employees and helps ensure greater security and regulatory compliance.
Technical Note: Opendock uses the SAML 2.0 protocol for SSO. Other protocols are not currently supported, however if you have a specific requirement please let us know about it.
How it works
Once your Org has SSO configured properly, your users can authenticate (login) to Opendock directly from your Identity Provider (IdP) such as Azure ActiveDirectory or Okta and access Opendock Nova without worrying about a separate username and password to manage.
Technical Note: This is known as the IdP-Initiated SSO flow. Service Provider (SP) initiated flows are not currently supported.
By default, users must be manually created in Opendock ahead of time before they can login via SSO. Users' Opendock roles are managed solely within Opendock. However if you wish to manage user creation/updates from your IdP you can use our optional Provisioning system (see section below for details on usage).
Configuring SSO in Opendock
- Navigate to the My Organization page and then select the SSO CONFIG tab.
- Generate your IdP Metadata URL from your IdP, paste it in the IdP Metadata URL field in Opendock and click SAVE. Note that your IdP must be able to provide this metadata URL, or you cannot use it with Opendock SSO.
- You can leave the SSO Enabled toggled to no for now. This will allow you to test out SSO before "officially" switching it on. You should also definitely leave the Forbid password logins option set to no for now (more details about both of these options below).
- Configure your IdP:
- Note that some details of setting up your IdP to work with Opendock will be unique to your business and your particular IdP and beyond the scope of this document. We provide the following to inform you of our requirements for SSO, and to assist with setup as best we can:
- Use the information under the Opendock Service Provider Metadata section to configure your IdP. If your IdP supports it, you can use the provided Metadata URL. If not, we also provide you with the Entity ID and Assertion Consumer Location values, which you can easily copy by clicking the copy icon on the right.
- There must be a claim named email that contains the user's email address as it is in Opendock.
- The SAML Certificates must be signed with SHA-256 for both response and assertion.
Now you can test this with a real user by authenticating via your IdP into Opendock. If this works for your test user, then proceed with the following sections.
- SSO Enabled
Once you are able to do a test login via SSO, you may want to "officially" enable SSO for your org. To do that just set the SSO Enabled toggle to yes and click SAVE. Now when users are created, they will no longer receive an email from Opendock asking them to set their password as authentication is expected to happen via SSO.
- Forbid password logins
Once you are sure things are working properly, you may want to lock the system down so that users in your Org can no longer login via password, but must use SSO instead. If you want this behavior, then set Forbid password logins toggle to yes and click SAVE. Now all users (except those with Owner role) will be denied access if they attempt to login via email/password, and they will also not be able to reset their password. They must instead login via SSO.
- API integrations: Since API access requires the use of email/password to login, you must make sure the user(s) that are utilized in any API integrations have an Owner role when this setting is turned on, otherwise your integrations will start to fail.
Azure Active Directory Tips
Here is a high-level overview of how to get going with Opendock SSO for those of you using Azure AD:
- Create an Enterprise Application for Opendock on which to setup SSO
- Add the Basic SAML configuration information for the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL)
- Add a claim named email with a value of user.email
- Set the SAML Signing Certificate > Signing Option to Sign SAML response and assertion
- Add Users (or Groups) to the application
- Copy the App Federation Metadata URL to Opendock.
Opendock SSO has support for provisioning, which is a system for allowing you to create and update users in your Opendock Org via your IdP (Identity Provider). So instead of having to manually create users in Opendock, and having to manually update their role, etc, you can use provisioning to have this done automatically when users attempt to SSO into Opendock. This can ease user identity management, giving you one single place to create/configure your users (your IdP).
The provisioning system works by having you set up certain extra claims (attributes) in your IdP with the information necessary for Opendock to create (or update) a user on the fly (just in time). You can "opt-in" to using provisioning by setting the "provision" claim to the string value "yes". With that set, Opendock will require you to also set the following claims as well:
|provision||Set this to the literal string "yes" to enable provisioning mode.|
|firstName||Set this to the user's first name (given name).|
|lastName||Set this to the user's last name (surname).|
Set this to a string value of the desired Opendock role you wish this user to have. Valid values are:
Set this to a comma separated list of warehouse id's (UUIDs) that you wish to restrict this user to. See note below on how to obtain warehouse id's.
If you do not wish to restrict your user to specific warehouses, you can set this claim to the string "all" and they will be able to access all of your warehouses.
Note: You can obtain each warehouse's id by fetching all warehouses via API call (GET /warehouse) and grabbing the desired id's out of the JSON data. Or you can also do this via the Opendock UI by just browsing to each warehouse's info page, and grabbing the id out of the URL in the browser:
With all of this set up correctly, any new user in your IdP should be able to SSO into your Opendock Org without you having to do anything on the Opendock side. The first time the user attempts to SSO in, Opendock will create their user account within your Org on the fly, and they will get logged in seamlessly, there is nothing noticeable to the user. In the future when that user SSOs in again, any changes to the fields above will get automatically synced over (updated) to their Opendock user account.
Note: This provisioning system does not handle user deletion, you will still have to manually remove users from your Org via the Opendock UI (or API).