DotLoop Single Sign On Implementation

Introduction
The Dotloops Single Sign on supports SAML 2 Standards. The Security Assertion
Markup Language 2.0 is a version of SAML standard used for exchanging authorization
and authentication data between the servers typically, IDP and SP.

Typically, the

messages exchanged contain "assertions" that state information about a given user. The
receiving server must believe the assertions to be true, so a trust must be established
between the two servers before communication can take place. SAML can be used for
many purposes, but the scope of this document is to explain the SSO capabilities of SAML.
The Identity provider provides the authentication and verification of the users identity.
The Service provider are providers who provide access to end users.
In the context of Single Sign-On (SSO), an assertion from the source server or
"Identity Provider" will contain an assertion that "user X logged in to our server at Y time
and date and is currently logged in and authenticated". If the message is from a trusted
source, then the recipient server must log that user in as well. The link between the user
ID provided and the user ID in the receiving system (or "Service Provider") must either be
established beforehand or established as part of the SSO process.

Integration with Dotloop

To integrate Dotloop with Identity providers, we need few information. Since
Dotloop follows SAML standards, Dotloop requires SAML metadata along with unique
Entity Id of the Identity providers. Metadata ensures a secure transaction between an
identity provider and a service provider. The identity provider should share their SAML
metadata which provides information about the SAML endpoints along with key
certificates. These certificates can be either signed or encrypted.
The sample SAML metadata for the Identity provider is shown below, (few attribute
sections are omitted for simplicity)
<md:EntityDescriptor
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
entityID="https://idp.example.org/SAML2">
<!-- insert ds:Signature element -->
<!-- insert md:IDPSSODescriptor element (below) -->
<!-- insert md:AttributeAuthorityDescriptor element (not shown) -->
<md:Organization>
<md:OrganizationName xml:lang="en">
SAML Identity Provider
</md:OrganizationName>
<md:OrganizationDisplayName xml:lang="en">
SAML Identity Provider @ Some Location
</md:OrganizationDisplayName>
<md:OrganizationURL xml:lang="en">
http://www.idp.example.org/
</md:OrganizationURL>
</md:Organization>
<md:ContactPerson contactType="technical">
<md:SurName>SAML IdP Support</md:SurName>
<md:EmailAddress>mailto:saml-support@idp.example.org</md:EmailAddress>
</md:ContactPerson>
</md:EntityDescriptor>

Integration with Identity Providers

Dotloop provides certain information to Identity providers just like the above to
have smooth integration. The Dotloop provides unique Entity Id which will be unique
across the application along with SAML Metadata. The SAML metadata contains the
complete information about the end point assertions and the certificate information.
The sample SAML metadata is shown below, (the certificates are removed for simplicity)

The actual Entity Id and SAML Metadata can be provided upon request. The identity
providers can send an email to support@dotloop.com to request for valid SAML
Metadata.

Dotloop Assertion Consumer Service Endpoint

The below endpoint URL consumes the signed Assertion from the Identity Providers. The
Identity providers has to send their signed assertion about the user information to the
below endpoint URL.
Assertion Consumer Service Endpoint URL:
https://stage.dotloop.com/my/saml/SSO/alias/dlSamlAlias
The Dotloop supports three types of Assertion bindings namely,

HTTP-Artifact

HTTP-POST

PAOS

The complete information of the assertion consumer service can be found at the SAML
Metadata provided by the Dotloop.

Identity Provider initiated SSO

In Identity provider initiated Single Sign on, the identity provider (IDP) is configured
with specialized links that refer to dotloop system. This link actually points to local IDPs
single sign-on service and pass parameters to the service identifying dotloop. So instead
of visiting dotloop directly, the use accesses the identity provider site and clicks on one
of the links to gain access to dotloop. This action triggers the creation of SAML Assertion
which will be transported to dotloop through HTTP-POST binding.
The process is as follows,
1. If the user does not have valid logon security context at the identity provider, at
some point the user will be challenged to supply their credentials to the identity
provider site.

2. The user provides valid credentials and a local logon security context is created
for the user at the Identity provider.
3. The user selects a menu option or link on the Identity Provider to request access to
dotloop website. This causes the Identity Provider's Single Sign-On Service to be
called.

4. The Single Sign-On Service builds a SAML assertion representing the user's logon
security context. Since a POST binding is going to be used, the assertion is digitally
signed before it is placed within a SAML <Response> message. The <Response>
message is then placed within an HTML FORM as a hidden form control named
SAMLResponse.(If the convention for identifying a specific application resource at
the SP is supported at the Identity Provider and dotloop, the resource URL at
dotloop is also encoded into the form using a hidden form control named
RelayState.) The Single Sign-On Service sends the HTML form back to the browser

in the HTTP response. For ease-of-use purposes, the HTML FORM typically will
contain script code that will automatically post the form to the destination site.
5. The browser, due either to a user action or execution of an auto-submit script,
makes an HTTP POST request to send the form to the dotloop's Assertion Consumer
Service (dotloop assertion consumer service endpoint URL is mentioned in the
above section). Dotloops Assertion Consumer Service obtains the <Response>
message from the HTML FORM for processing. The digital signature on the SAML
assertion must first be validated and then the assertion contents are processed in
order to create a local logon security context for the user at dotloop. Once this
completes, the dotloop retrieves the RelayState data (if any) to determine the
desired application resource URL and sends an HTTP redirect response to the
browser directing it to access the requested resource (not shown).
6. An access check is made to establish whether the user has the correct
authorization to access the resource. If the access check passes, the resource is
then returned to the browser.

Dotloop SAML SSO Testing Instructions

There are two methods to establish SSO with dotloop.

SAML Request / SAML Response Interaction

1. User is logged in to <<Identity Partner System>>
2. User clicks on a link/button in <<Identity Partner System>> to sign in to dotloop
3. <<Identity Partner System>> makes a call to
https://stage.dotloop.com/my/saml/login/alias/dlSamlAlias?idp=<<IdentityPartnerEntityId>> to

get the SAML request

4. <<Identity Partner System>> receives the SAML request, processes it and generates a
SAML response
5. <<Identity Partner System>> sends the SAML response
to https://stage.dotloop.com/my/saml/SSO/alias/dlSamlAlias via browser through HTTP POST

6. dotloop validates the SAML response and if successful takes the user to dotloop
homepage.

Only SAML Response Interaction

(Numbers marked in above diagram are explained below with respect to dotloop integration)

1. Allow user to sign in to <<Identity Partner System>>

2. User is logged in to <<Identity Partner System>>
3. User clicks on a link/button in <<Identity Partner System>> to sign in to dotloop
4. <<Identity Partner System>> sends the Signed SAML response
to https://stage.dotloop.com/my/saml/SSO/alias/dlSamlAlias via browser through HTTP POST
(Step 5 in above figure)

7. dotloop validates the SAML response and if successful takes the user to dotloop
homepage.

Sample SAML Request

Sample SAML Response

SAML SSO Setup Checklist

o

Metadata xml from both sides (dotloop and from Identity providers)

SAML Issuer or entity Id which uniquely identifies the Identity provider

References

http://www.oasis-open.org/committees/download.php/27819/sstc-saml-tech-overview-2.0-cd02.pdf
http://en.wikipedia.org/wiki/SAML_2.0