The attached guide is intended for Information Technology professionals who plan to leverage their existing SSO implementation to bypass the Documoto login screen.
- Quick Start Notes
- How Documoto Supports SSO
- Security Assertion Markup Language (SAML)
- SAML Components
- General SSO Communication Flow
- What Needs to Be Sent to Documoto
Single-Sign-On ("SSO") enables users to automatically login to the Documoto application, bypassing the standard Documoto login page. The user is first verified by logging into your company’s portal, then by accessing a link which in turn automatically forwards and logs the user into Documoto.
Quick Start Notes
- Documoto only supports SP-initiated SSO
- SAML 2.0 only
- Your metadata file needs to be publicly accessible via URL
- Example of Documoto’s metadata file:
- Documoto does not support SSO logout
- Must use SAML Assertion signing
- The following attributes must be sent to Documoto:
- User Group(s)
- Email Address
- Note: in Documoto, the user's email address will be assigned to the 'username' field. For more information on this, please see the 'What Needs to be Sent to Documoto' section below.
- SSO can be combined with URL Parameters
- For example, common URL parameters can hide the application header and remove user preferences.
How Documoto Supports SSO
Documoto supports user creation and updating via SSO. Because of the way Documoto is architected, a user has to exist in our system in order to view content. However, Documoto does not store any SSO users’ password information. As such, the user cannot login via the standard Documoto login page.
Security Assertion Markup Language (SAML)
SAML is the XML-based standard data format for exchanging authentication and authorization data between parties. SAML is designed to be platform and browser agnostic.
To understand SAML, you should have an understanding of the components that comprise SAML, as well as common SSO terminology.
- Principal (User): user looking to get access to an application
- Identity Provider (IdP): where the user initially authenticates
- When connecting your existing SSO to Documoto, the IdP is your server
- Service Provider (SP): relies on the IdP’s identity assertion before providing a service
- When connecting your existing SSO to Documoto, the SP is Documoto.
General SSO Communication Flow
- The IdP (your server) has a public and private key.
- You supply a metadata endpoint that advertises your public key.
- You make an authentication/authorization decision and either:
- Redirect the user to Documoto, with a SAML response that has been signed with your private key
- Tell the user they do not have a session
- Documoto uses your IdP’s public key to verify the signature. If it passes, Documoto authenticates the user to our system using the organization/user group/email address provided by the SAML response.
The SSO communication process is initiated by forwarding a user to the following URL via web browser:
- Integration (test) environment: https://integration.digabit.com/Portal/saml/?tk=[yourTenantKeyHere]&sso=true
- Production environment: https://documoto.digabit.com/Portal/saml/?tk=[yourTenantKeyHere]&sso=true
When Documoto receives the URL above, we know you want to login via SSO. Documoto will then redirect back to you (step 3+) with an AuthnRequest.
What Needs to Be Sent to Documoto
Documoto requires the following information to successfully login a user via SSO:
- Metadata URL
- Provide the URL to your metadata file for configuration in Documoto
- Define the following field names, as specified by your Identity Provider:
- IdP attribute used to send Documoto Organization
- IdP attribute used to send Documoto User Group
- IdP attribute used to send Documoto Email Address
Documoto will then map the IdP field names to the appropriate Documoto fields.
Note: Because Documoto maps the IdP email address field to the
Documoto username field, Documoto cannot support usernames
that are not an email address. If you have questions or
concerns on this, please reach out to your assigned Customer