Security Assertion Markup Language (SAML) is used to delegate user authentication to a third party identity service, such as Active Directory Federation Services (ADFS) or OneLogin.
How It Works ¶
Service Provider: Dozuki
Identity Provider: Client Organization's Identity Service
Client: The user
Authentication Timeline ¶
- Non-authenticated client requests a page on Dozuki.
- Dozuki redirects the client to the Identity Provider URL specified in /Manage/security.
- Client enters their login information at the Identity Provider URL.
- Identity Provider signs a document saying that the client is authenticated. This document includes their userid, email, and username.
- Client POSTs the signed document to Dozuki's specified remote_login endpoint.
- Dozuki verifies that the document is signed correctly using the Identity Provider's X.509 certificate which is also specified in /Manage/security.
- Dozuki grants the client an authentication token.
- Dozuki redirects the client to whichever page they were originally trying to view.
This is a picture representation of the above timeline:
CC BY-SA 3.0 https://en.wikipedia.org/wiki/File:Saml2-browser-sso-redirect-post.png
SAML Settings ¶
Identity Provider URL: This is the URL to redirect users to when they are unauthorized.
Identity Provider Logout URL: Users are redirected to this URL after they log out of Dozuki.
Identity Provider X.509 Certificate: This is used to verify that the document saying that the user is authenticated with the Identity Provider is actually from the Identity Provider.
Not Editable ¶
AssertionConsumerService: This is the URL that the Client POSTs the signed authentication document from the Identity Provider to. Currently /Guide/User/remote_login.
SingleLogoutService: The URL that handles logging out a user. Currently /Guide/logout.
Exporting Settings ¶
We provide an endpoint for downloading our SAML settings in a file called metadata.xml. Dozuki clients can upload this XML document to their Identity Providers to setup SAML with Dozuki.
This can be found at /Guide/User/remote_login/saml_metadata. A link can be found to it on /Manage/security.
Microsoft provides documentation for setting up ADFS as a SAML Identity Provider.
When editing Claim Rules, it is necessary to map the following LDAP Attributes to Outgoing Claim Types:
- Send the Active Directory unique identifier (guid, etc.) as userid.
- Send the Active Directory display name as username.
- Send the Active Directory email as the email.
This image shows what the Edit Rule dialog should look like:
You can test your SAML setup with OneLogin by using the OneLogin SAML Test Connector
Existing Dozuki User Accounts ¶
What if user accounts already exist on my Dozuki site? Will SAML automatically recognize these, or will a new user account be created when a person with an existing account logs in using SSO/SAML?
- Dozuki automatically checks for a matching email address on existing accounts before creating a new account on the first SAML login. If a matching email address exists in Dozuki, the SAML login will automatically add the unique identifier userid passed over from ADFS or OneLogin to the Dozuki user account for future logins.
User Plan Limitations ¶
What if I have a limit to my user plan? If each SSO/SAML login automatically creates a new Dozuki user account, what happens when I reach my user plan limit for accounts?
- If you reach the user plan maximum for user accounts on your Dozuki site, any subsequent SSO/SAML login attempts requiring new account creation will result in an error page forbidding access to Dozuki.
- Existing accounts will still be able to access Dozuki.
- You can contact your Account Executive to add more users to your plan once you've reached your maximum. Alternatively, you can deprovision/disable users within Dozuki to free up seats for new accounts within Dozuki.
- You can also negotiate a customized billing plan with your Account Executive to allow unlimited user accounts that will pro-rate billing for added accounts throughout the billing cycle. Contact firstname.lastname@example.org to submit a request.