What is SSO?

SSO is an authentication and access control technology that 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 log in 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 the section below for details on usage).

Configuring SSO in Opendock

Initial Setup

1. Navigate to the My Organization page and then select the SSO CONFIG tab.
2. 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.
3. 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 are below).
4. 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 Settings

• 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.
  
  Note: SSO Provisioning will NOT work until you set SSO Enabled to yes.
  
  
• 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:

1. Create an Enterprise Application for Opendock on which to setup SSO
2. Add the Basic SAML configuration information for the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL)
3. Add a claim named email with a value of user.email
4. Set the SAML Signing Certificate > Signing Option to Sign SAML response and assertion
5. Add Users (or Groups) to the application
6. Copy the App Federation Metadata URL to Opendock.

Configuring Provisioning

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:

owner
admin
operator
attendant
spectator

Note: You must set the SSO Enabled setting to yes (see section above) for the SSO Provisioning system to function properly.

Note: We provide a list of all of your warehouses and their ids at the bottom of the SSO Config tab so you can easily copy and paste those into your warehouseAccessList claim, if desired.

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).