DocuSign Information Guide. Single Sign On Functionality. Overview. Table of Contents

Transcription

1 DocuSign Information Guide Single Sign On Functionality Overview The DocuSign Single Sign On functionality allows your system administrators to maintain user information in one location and your users can access the DocuSign console with their existing network credentials. This feature is available for the Advanced Administration Module and DocuSign Enterprise Edition plans, but requires some extra setup requirements. Customers wanting use the single sign-on with SAML must engage with DocuSign Professional Services to ensure the set up functions correctly. This guide provides information about how the functionality works and general set up information for Single Sign On functionality. Table of Contents How it Works... 2 Supported Protocols... 2 Setting Up Single Sign On for Your Account... 2 DocuSign Secure Token Service Requirements... 3 Maintaining Your SAML Configuration... 5 For More Information... 6 Example SAML 2.0 Service Provider Metadata XML... 6 Example SAML 2.0 Service Provider Initiated AuthNRequest... 8

2 2 How it Works Single Sign On (SSO) influences how both users and system administrators interact with the DocuSign service. DocuSign supports multiple specification of the Security Assertion Markup Language (SAML) for SSO integrations. Note: DocuSign supports Lightweight Directory Access Protocol (LDAP) on a limited basis. DocuSign requires that all LDAP implementations be done with direct involvement from DocuSign Professional Services. Speak with your Account Manager and DocuSign Professional Services for more information on implementing LDAP. Users There are two general methods used to set up SSO to allow users to access DocuSign. A user goes to the DocuSign console and enters their address. DocuSign recognizes the domain for the user and directs them to their Identity Provider application where they enter their network credentials to log on to their DocuSign account. A user is already logged on to their primary network. The network has a link to the DocuSign console and users are automatically logged in to the DocuSign console when they access the console through the link. System Administrators When SSO is enabled, system administrators can use their current authentication systems to manage user access to the DocuSign service, removing the need for users to manage their own DocuSign account logins. DocuSign also supports mixed access of both DocuSign password and SSO access. System administrators still need to add, remove and modify users and user Permissions through the DocuSign console or DocuSign Account Management API. Supported Protocols DocuSign SSO currently supports the following SAML protocols: OASIS SAML 2.0 WS-Federation SAML 1.1 Setting Up Single Sign On for Your Account In order to use the DocuSign SSO with SAML, you must have a DocuSign account and it is recommended you have a public Secure Token Service (STS) or Identity Provider (IdP) in order to issue SAML assertions to access the DocuSign Console. Contact your DocuSign Account Manager to set up a meeting with Professional Services to start the process. Professional Services will help you determine the best SSO method for your organization, coordinate configuring and testing for your account. You will be asked to provide the following information to configure SSO for your account: Your X.509 certificate. DocuSign uses the public facing certificate. The certificate must be from a trusted certificate authority. All SAML/SSO exchanges will need to be signed with the X.509Certificate before being sent to DocuSign for consumption.

3 3 If you choose to use the Service Provider initiated method where DocuSign traps on domains and redirects to the customer IdP, you must provide the suffixes used to log on to the DocuSign console. You can have multiple domains in your setup, but the domains must be unique to your organization. DocuSign requires proof of ownership of domains. The DocuSign IdP/STS requirements and X.509 certificate requirements are explained in the next section. Getting Started The DocuSign demo ( application environment can be used to setup the configuration. The account must have Single Sign On privileges enabled in the DocuSign management console. In general, DocuSign recommends starting with a set up where users access DocuSign from within your network and then, if needed, move to the domain method. DocuSign also requests, but does not require, that customers have a test or staging environment that can be used as IdP/STS during the initial setup and testing with DocuSign. If any issues arise that need further investigation, DocuSign has a QA environment that the Development staff can use to debug and step through code path execution to examine issues. DocuSign Secure Token Service Requirements In order to implement a Single Sign On session with the DocuSign Web Console, you must provide your own Secure Token Service (STS) or Identity Provider (IdP) to issue SAML assertions for access to the DocuSign Web Console. Note: The information in this document is subject to change during the development process at DocuSign. Information about connecting to the DocuSign API with SSO will be addresses later. DocuSign does not currently provide SAML access to our API. Currently DocuSign recommends using the Send On Behalf Of functionality in conjunction with our API architecture. DocuSign Information DocuSign has implemented the Windows Identity Foundation (WIF) to control our Single Sign On functionality. DocuSign is able to consume Microsoft SAML 1.1 and SAML 2.0. Service Provider Endpoint URL When setting up you system, you must point to the Endpoint URL of the primary DocuSign environment for your account (for example: if your account is on the DocuSign NA2 production server, your Endpoint should use If you do not know the primary environment for your account, contact your Account Manager. The following Endpoint URLs are associated with DocuSign environments for SAML 1.1 and SAML 2.0: Environment WS Federation 1.1 OASIS SAML 2.0 QA Demo North American Production

4 4 Environment WS Federation 1.1 OASIS SAML 2.0 Europe DocuSign Requirements X.509 Certificate Exchange DocuSign will exchange X.509 certificates with our STS clients. These certificates must be from a trusted certificate authority and be the public facing cert (i.e. no private key attachment). All SAML/SSO exchanges will need to be signed with the customer s DocuSign X.509 certificate before being sent to DocuSign for consumption. DocuSign has some restrictions on accepting self-signed certificates. If you use self-signed certificates, there will be extra setup requirements and fees associated with the integration. SAML 2.0 Service Provider Metadata XML The DocuSign service provider application has metadata available to describe assertions and signatures expected from Identity Provider applications. The Example SAML 2.0 Service Provider Metadata XML section provides an example of the SAML metadata.xml. The URL s for accessing the metadata for various environments are as follows: Production: Production NA2: Production Europe: Demo: SAML 2.0 Service Provider Initiated AuthNRequest Post The DocuSign service provider can provide a SP initiated AuthNRequest HTTP POST to an Identity Provider application. The Example SAML 2.0 Service Provider Initiated AuthNRequest Post section shows an example of the SAML AuthNRequest POST data content. DocuSign Claims DocuSign must have the following claims presented in the SAML assertion and these claims must match the credentials of the membership in the DocuSign account: Required Optional

5 5 Note: If the name assertion cannot be generated by the customer, the assertions firstname and lastname must be used together with the address assertion. If the Client STS has additional claims, you need to provide them. Please contact your DocuSign Account Manager with the additional claims. DocuSign does not currently auto-provision members from SAML assertion credentials. Therefore, memberships will need to be pre-provisioned with the and complete username that will be received from the customer STS or ADFS system in the SAML token. Other Assertion Elements The Assertion elements listed below should be available in the request: saml:assertion attribute ID should always be unique for the client. saml:conditions attributes NotBefore and NoOnOrAfter using the standard time range. saml:audiencerestriction identifies the intended realm. Query Parameters WS Federation requires the following query parameters (as hidden input variables) with the Assertion request via POST: wa wsignin1.0 wtrealm target realm wresult contains the entire SAML assertion XML node structure. All left angle brackets and double quotes must be escaped, (i.e. < ") wctx this optional query parameter is reserved for DocuSign use to maintain state information, to deeplink to a senders/recipients envelope. OASIS query parameters: RelayState - this optional query parameter is reserved for DocuSign use to maintain state information, to deeplink to a senders/recipients envelope. Maintaining Your SAML Configuration After your SSO is enabled, you will be able to change your Identity Provider Endpoint URL (if used with your setup) and upload a new X.509 certificate. This allows you to keep your certificate up to date without having to contact DocuSign. To access your SAML Configuration page, go to the web console Preferences, in the Navigation panel click Features, scroll down to the Advanced heading and then click SAML Configuration. The SAML 2.0 Configuration page is displayed, allowing you to modify the endpoint URL and upload a new X.509 signing certificate.

6 6 For More Information For more information about additional DocuSign features, go to the DocuSign website. Example SAML 2.0 Service Provider Metadata XML The following xml sample is an example of the DocuSign service provider metadata: <md:entitydescriptor entityid=" ID="_ce5716b6-9f54-43ae-b48cdb79dbc144e3"> <Signature> <SignedInfo> <CanonicalizationMethod Algorithm=" <SignatureMethod Algorithm=" <Reference URI="#_ce5716b6-9f54-43ae-b48c-db79dbc144e3"> <Transforms> <Transform Algorithm=" ><Transform Algorithm=" <InclusiveNamespaces PrefixList="#default md saml ds xs xsi"/> </Transform> </Transforms> <DigestMethod Algorithm=" <DigestValue>yMpCIZNnxiPxa37p0ucF4a/B9hM= </DigestValue> </Reference> </SignedInfo> <SignatureValue>w09quLXhTI5VU2UUn09FXPXLWHEW70m/qoMKhzAAHOkgRzUg4xQe64DZUCOqK3UeEtd5V QHrOa+L1Bt66wiUe0PuFBoVkvGRhXRi0/mK20vptkbboppstfYkgootAESa2ad17PG8KOMxZ4WgxFClvL4V+2jsJP 2KE7f/7hpMIltH1XY38HkHb0mdnKlSNa+dwN32M1PxRAd/gpIGk7FOmCXiDzcu2x9ziSocVl3bIaFEUCc6/NcuQhB lfwadqmarxmd5isyjzp1nngdkfipu9n1wwe4kajwujya/j73nzv2hevefn6sfqtu3wuhkcudcackoadwwm+4bipz6 4OU0LA== </SignatureValue> <KeyInfo> <X509Data>

7 7 <X509Certificate>MIIGSTCCBTGgAwIBAgIQU5JinnCKgrxK6bYLP0QrGDANB gkqhkig9w0baqufadcbvjelmakga1uebhmcvvmxfzavbgnvbaotdlzlcmltawdulcbjbmmumr8whqydvqqlexzwzx JpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQgaHR0cHM6Ly93d3cudmVyaXNpZ24 uy29tl3jwysaoyykwnje4mdyga1ueaxmvvmvyavnpz24gq2xhc3mgmybfehrlbmrlzcbwywxpzgf0aw9uifnttcbt R0MgQ0EwHhcNMTEwOTI5MDAwMDAwWhcNMTMxMDE1MjM1OTU5WjCCASIxEzARBgsrBgEEAYI3PAIBAxMCVVMxGzAZB gsrbgeeayi3paibahqkv2fzagluz3rvbjedmbsga1uedxmuuhjpdmf0zsbpcmdhbml6yxrpb24xejaqbgnvbautct YwMjI4NDYxODELMAkGA1UEBhMCVVMxEzARBgNVBAgUCldhc2hpbmd0b24xEDAOBgNVBAcUB1NlYXR0bGUxFzAVBgN VBAoUDkRvY3VTaWduLCBJbmMuMR4wHAYDVQQLFBVQcm9kdWN0aW9uIE9wZXJhdGlvbnMxMzAxBgNVBAsUKlRlcm1z IG9mIHVzZSBhdCB3d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNTEZMBcGA1UEAxQQd3d3LmRvY3VzaWduLm5ldDCCA SIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAOqNnne0roWcKNb/z04P18HFsvbqyoxWZjoG0g+g63FlpmZf7O gqj8a1tmyxqncrgvoleyz0jgxrm55howvnl9vzlbojafsh8pvgauhnxca961rohlchzvyn9eirpa1yncbavrcscpg rx8mrofyplxu8i2h011hiw9x9n+/+oz9vaafkxbtrej5n2r8zhom+srqbt8qkmbt+ih1ywdiz4uflhcwvuybxwlp3 hhed6+9ubzuabotn7ebpumaq6cgvdajz3nyokawd72zxbhhbcz/jj6uh+mgcwnp7mlcvwj8ws7wytlkqtzqcaa5dh 0FTzBnDfAUkVYY8AgAcGKMgBLECAwEAAaOCAdowggHWMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgWgMEQGA1UdIAQ9MD swoqylyiziayb4rqehfwywkjaobggrbgefbqccarycahr0chm6ly93d3cudmvyaxnpz24uy29tl2nwcza+bgnvhr8 ENzA1MDOgMaAvhi1odHRwOi8vRVZJbnRsLWNybC52ZXJpc2lnbi5jb20vRVZJbnRsMjAwNi5jcmwwNAYDVR0lBC0w KwYIKwYBBQUHAwEGCCsGAQUFBwMCBglghkgBhvhCBAEGCisGAQQBgjcKAwMwHwYDVR0jBBgwFoAUTkPIHXbvN1N6T /JYb5TzOOLVvd8wbwYIKwYBBQUHAQEEYzBhMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC52ZXJpc2lnbi5jb20wOQ YIKwYBBQUHMAKGLWh0dHA6Ly9FVkludGwtYWlhLnZlcmlzaWduLmNvbS9FVkludGwyMDA2LmNlcjBuBggrBgEFBQc BDARiMGChXqBcMFowWDBWFglpbWFnZS9naWYwITAfMAcGBSsOAwIaBBRLa7kolgYMu9BSOJsprEsHiyEFGDAmFiRo dhrwoi8vbg9nby52zxjpc2lnbi5jb20vdnnsb2dvms5nawywdqyjkozihvcnaqefbqadggebacgczfodqwe4x071e H7Qf6z5dQ1wM6/GsKrXKlkyuhPkrrKD7TaU916FVYFsEY3R94FemYkiWQ3B4eank/vxtFgXqvK+0Rl/awZCBmtKdo jffwj/e3/hdugos74crljet6ughyqohgp0vn6nc6b1dkhpkc3zmg6szemyir0kaxj1km9/dd1cbo39d1rgtpmnl0p 1W0eVkTrgMI77ZQDP9F39+8wWtOv0prDRUQQ2xoqPBzilWI8fA+lrFQg7BoS34yxOVWT7pc1jZJAaG1OGP3gpDrbv ohqmeuejb6pknqtondw90p3nacj2w3gvmtznmzpyxyj2ij8ub2ot5ilhe4q= </X509Certificate> </X509Data> </KeyInfo> </Signature> <md:spssodescriptor ID="_5d e7f4-443a-bed8-fdd6b321d17e" protocolsupportenumeration="urn:oasis:names:tc:saml:2.0:protocol" AuthnRequestsSigned="true" WantAssertionsSigned="true"> <md:nameidformat>urn:oasis:names:tc:saml:2.0:nameid-format:transient </md:nameidformat> <md:assertionconsumerservice Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location=" index="1" isdefault="true"/> <md:attributeconsumingservice index="1" isdefault="false"> <md:requestedattribute isrequired="true" Name="urn:oid: " NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName=" "/> <md:requestedattribute isrequired="true" Name="urn:oid: " NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="commonName"/> <md:requestedattribute isrequired="false" Name="urn:oid: " NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="surname"/> <md:requestedattribute isrequired="false" Name="urn:oid: " NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="givenName"/> </md:attributeconsumingservice> </md:spssodescriptor> <md:organization> <md:organizationname xml:lang="en">docusign </md:organizationname> <md:organizationdisplayname xml:lang="en">docusign </md:organizationdisplayname> <md:organizationurl xml:lang="en"> </md:organizationurl> </md:organization> <md:contactperson contacttype="technical"> <md:givenname>docusign </md:givenname> <md:surname>support </md:surname> </md: address>

8 8 </md:contactperson> </md:entitydescriptor> Example SAML 2.0 Service Provider Initiated AuthNRequest The following xml sample is an example of the DocuSign service provider initiated AuthNRequest POST. The issuer node inside the AuthNRequest POST or REDIRECT will be specific to the server environment in DocuSign that generated it. For example if it was generated by the issuer node will state If generated by na2.docusign.net, then it will state na2.docusign.net. <saml:issuer xmlns:saml="urn:oasis:names:tc:saml:2.0:assertion"> </saml:issuer> <Signature xmlns=" <SignedInfo> <CanonicalizationMethod Algorithm=" /> <SignatureMethod Algorithm=" /> <Reference URI="#_38e0e031-2a68-4e64-b6bb-99c5b20bd1e9"> <Transforms> <Transform Algorithm=" /> <Transform Algorithm=" <InclusiveNamespaces PrefixList="#default samlp saml ds xs xsi" xmlns=" /> </Transform> </Transforms> <DigestMethod Algorithm=" /> <DigestValue>p7tq1i9HeBksd0NuJQZieAqOPnk= </DigestValue> </Reference> </SignedInfo> <SignatureValue>nAY3L/fIYNSL9YUD+sj9idMzuRqDON5CzmVweZyO7kP7BZabGYuyL5yziBpC9Y3OnckgT 8oVfW/C9OMZCKFMWG/hvBugBi5A5+q4kZ1hAChtKQZlgJsqDqc0c8eMjgXSYPNbKo3VVv1dfBcN66Ba6ZpUF60q9/ a5hjxj34x6sc4= </SignatureValue> <KeyInfo> <X509Data> <X509Certificate>MIIBnjCCAQcCBEbTmdAwDQYJKoZIhvcNAQEEBQAwFjEUMBIGA1UEAxMLd3d3LmlkcC5j b20whhcnmdcwodi4mdm0mzeywhcnmtcwodi1mdm0mzeywjawmrqwegydvqqdewt3d3cuawrwlmnvbtcbnzanbgkqh kig9w0baqefaaobjqawgykcgyeao31q3mjzayxfzkldulcnanc/kg+rdfw+olydp+rubvwnt8x5jtiutcp8iq46tn EUFskmsonUb5AnG+zOCcawb2dJr8kBtCNhfi/TufZGBQNjuAxNMi34yIgRdGinaznHgclrAIIZTyKerQqYjPL1xRD sfgpzqggi/2opzn8nv5kcaweaatanbgkqhkig9w0baqqfaaobgqbmnwfn+98aybuqkfjfr69s9bvbvytk+hsx3gx0 g4e5sltlkcsu03xz8aoet0my4rvuspadrzdrv+gegg7gdp/rsvcss3dkuyuuvuwbiitq/hj4ekukza8nierz3oz4x a1/bk88et7rvsv5bmoxgjbsevtidtvopv0g13duiqyrcw== </X509Certificate> </X509Data> </KeyInfo> </Signature> <samlp:nameidpolicy AllowCreate="true" xmlns:samlp="urn:oasis:names:tc:saml:2.0:protocol" />

9 9 Copyright, Trademark and Patent Information Copyright DocuSign, Inc. All rights reserved. For information about DocuSign trademarks, copyrights and patents refer to the DocuSign Intellectual Property page ( on the DocuSign website. All other trademarks and registered trademarks are the property of their respective holders. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of DocuSign, Inc. Under the law, reproducing includes translating into another language or format. Every effort has been made to ensure that the information in this manual is accurate. DocuSign, Inc. is not responsible for printing or clerical errors. Information in this document is subject to change without notice. Version: DocuSign Release (November 2013) If you have any comments or feedback on our documentation, please send them to us at: Summary of changes for this version: Clarified the Service Provider Endpoint URL section to say that customers must point to the Endpoint URL for the primary server for their account. Removed information about DocuSign Preview environment, which is no longer used.