Configuring SAML2 for Single Sign-On to Smartsheet (Enterprise Only)

Transcription

1 Configuring SAML2 for Single Sign-On to Smartsheet (Enterprise Only) This document is intended for technical professionals who are familiar with SAML and have access to the Identity Provider that will be configured for use with Smartsheet.com. It will walk you through Configuring your Identity Provider for SAML with Smartsheet, and configuring your Smartsheet account for use with your IdP. Revision Table of contents: Configuring Your Identity Provider for SAML with Smartsheet.com Configuring Smartsheet.com for use with your SAML Identity Provider (IdP) One IdP, one domain (most common scenario) IdP security certificate expiration and rollover SAML configuration states Appendix A: Sample assertion Required Attributes: Optional Attributes 1

2 Configuring Your Identity Provider for SAML with Smartsheet.com 1. Obtain the Smartsheet Metadata: saml2 sp metadata.xml 2. Configure a Relying Party within your Identity Provider using the Metadata provided. Details on how to do this are specific to your Identity Provider. Please consult your documentation for further details. 3. Smartsheet requires the following attributes to be asserted during the SAML exchange process: urn:oasis:names:tc:saml:2.0:nameid format:persistent The first assertion must contain a persistent Id that is the same for each user whenever they log in. The second is the user s address. Please see Appendix A at the end of this document for a sample assertion. Please see Appendix B at the end of this document for a list of our supported claim formats. 4. The following are recommended, but optional attributes: As their names indicate, the first represents a user s given name, and the second the user s surname. 5. Some SAML services may ask for additional information when configuring integration with Smartsheet: Assertion Consumer Service (ACS) URL: Audience Restriction: Note: Smartsheet supports SP initiated SSO only. IdP initiated SSO is not supported. 2

3 Configuring Smartsheet.com for use with your SAML Identity Provider (IdP) You must be a SysAdmin to configure SAML for your organization's Enterprise account. Ensure that your account is an Enterprise account by clicking on Account in the upper left corner and selecting Account Admin. On the Plan and Billing Info (default) page, make sure the Plan is Enterprise. If your plan is not Enterprise, please upgrade your account before proceeding. Accessing SAML configuration From the Account Admin form, select Security Controls. Click the Edit button in the Authentication section to open the Authentication form. 3

4 In the Authentication form, click not configured next to SAML to open the SAML Administration form. 4

5 One IdP, one domain (most common scenario) 1. Add IdP 1. Click Add IdP to open the Add IdP form. 2. Provide a descriptive nickname for your IdP. 3. Obtain the SAML Metadata XML for your IdP and paste it into the Metadata text area, or type in the URL where the metadata for your IdP can be accessed online. Consult your Identity Provider s documentation to determine how to obtain this. 4. Click Save. Smartsheet will validate the metadata. If the validation is successful (valid security certificate, etc.), the Edit IdP form will open. 5

6 2. Add domain 1. In the Edit IdP form, click Add Domain to open the Add Domain form. 6

7 2. Enter the name of the domain you want to be SAML enabled and click Save. 3. Once the domain name is saved, the Edit Domain form will open 3. Validate domain For security reasons, you must confirm that you control the domain in question. In the Edit Domain form, follow the instructions to validate your domain: 1. Create a DNS TXT record in your domain, exactly as instructed. 2. Once the record is created, click the Validate button to proceed. 3. Smartsheet will perform a DNS lookup to verify that the TXT record exists in your domain. The validation may fail if there is a delay in DNS propagation. If that happens, please attempt domain validation again later. 4. If the validation is successful, domain status will change from Not Validated to Inactive. IMPORTANT: The domain validation DNS record must always be present for the SAML configuration to remain valid. For that reason, do not remove the record even after the domain validation step is successfully completed. 4. Add CNAME (optional) Smartsheet provides the default SSO URL for your organization. You can add a shorter, more convenient CNAME instead, which may be easier to remember than the default URL we provide. 1. Create a CNAME DNS record in your domain and point it at sso.smartsheet.com. For example, "smartsheet.example.org IN CNAME sso.smartsheet.com" 2. In the Edit Domain form, enter the CNAME and click Add this field will only be displayed on the Edit Domain form after you ve clicked Validate. 7

8 3. It may take up to one hour for the change to take effect 5. Activate domain The ownership of the domain must be validated prior to activation. In the Edit Domain form, click Activate to activate the domain. The domain status will change from Inactive to Active. 8

9 6. Activate IdP The IdP must have at least one active domain prior to activation. In the Edit IdP form, click Activate to activate the IdP. The IdP status will change from Inactive to Active. 9

10 10 7. Enable SAML There must be at least one active IdP prior to enabling SAML. In the Authentication form, check the SAML box to enable SAML for your organization.

11 11 8. You can add additional IdPs and domains at any time by clicking edit configuration next to the SAML checkbox to open the SAML Administration form.

12 12

13 IdP security certificate expiration and rollover An expired security certificate will cause your Smartsheet SAML configuration to become disabled. To avoid any service disruption to your users, we urge you to make sure that your IdP security certificates are valid and up to date. Smartsheet regularly checks for expiring certificates and will notify organization administrators via 45 days and five days prior to the actual expiration date. If your SAML configuration has an IdP (OLD_IDP) with an expiring certificate, we recommend the following steps to minimize downtime for your users: 1. Create a new IdP (NEW_IDP) using metadata with a new security certificate. 2. Configure NEW_IDP (domains, etc.) so that its configuration is identical to that of OLD_IDP. 3. Deactivate OLD_IDP (if you have only one active IdP, you will need to disable SAML to do that). 4. Activate NEW IdP. It may take up to ten minutes for the activation to complete. 5. Don't forget to enable your SAML configuration if you had to disable it in an earlier step. 13

14 SAML configuration states SAML will be in one of three states: Not configured : No active IdPs Disabled : At least one active IdP, and SAML is not checked on the Authentication form. Enabled : At least one active IdP, and SAML is checked on the Authentication form. IdP will be in one of three states: Not configured : No active domains, or security certificate is expired Inactive : Valid metadata, valid security certificate, and at least one active domain Active : same as Inactive, plus not sharing entity ID with another active IdP, has no active domains in common with another active IdP, and is activated Domain will be in one of three states: Not validated : Not validated via DNS lookup Inactive : Validated via DNS lookup Active : Validated via DNS lookup, and is activated Additional configuration options 1. Adding domains to an IdP: There is no limit to the number of domains you can add. Domains within a given IdP must be unique. 2. Deactivating or deleting domains: open the Edit Domain form. If this is the only active domain within a parent IdP, you must first deactivate the IdP to deactivate or delete the domain. 3. Adding IdPs: There is no limit to the number of IdPs you can add. 4. Deactivating or deleting IdPs: open the Edit IdP form. If this is the only active IdP in your SAML configuration, you must first disable SAML to deactivate or delete the IdP. 5. Activating IdPs: To activate an IdP, make sure that it doesn t have the same entity ID as another active IdP and that it doesn t have any active domains in common with another active IdP. 14

15 Appendix A: Sample assertion 15 <saml2p:response xmlns:saml2p="urn:oasis:names:tc:saml:2.0:protocol" xmlns:xs=" ID="id " IssueInstant=" T20:50:56.659Z" Version="2.0"> <saml2:issuer xmlns:saml2="urn:oasis:names:tc:saml:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid format:entity"> <ds:signature xmlns:ds=" <ds:signedinfo> <ds:canonicalizationmethod Algorithm=" exc c14n#"/> <ds:signaturemethod Algorithm=" sha1"/> <ds:reference URI="#id "> <ds:transforms> <ds:transform Algorithm=" signature"/> <ds:transform Algorithm=" exc c14n#"> <ec:inclusivenamespaces xmlns:ec=" exc c14n#" PrefixList="xs"/> </ds:transform> </ds:transforms> <ds:digestmethod Algorithm=" <ds:digestvalue>nolry/cb/i62zwgd+twx5y1cbpo=</ds:digestvalue> </ds:reference> </ds:signedinfo> <ds:signaturevalue> Ql0Twt5JoQ8jUeDO5lDGUcOBaq8Ab7jLYvZ0pNx44edC5diDJ5H3O1hPiroK+mdjjsI/ZA05bhOVVFmLmmWy2Dt4kuaS/MAg 3cmwA9mR4nd8AwArlOTorrxkgwqRE/3o4w2NoIF9qvTbmfE89ncpwCIGJ4a4Inn2ZvM4cc9yCIk= </ds:signaturevalue> <ds:keyinfo> <ds:x509data> <ds:x509certificate> MIICmzCCAgSgAwIBAgIGATYsZIyyMA0GCSqGSIb3DQEBBQUAMIGQMQswCQYDVQQGEwJVUzETMBEG A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU MBIGA1UECwwLU1NPUHJvdmlkZXIxETAPBgNVBAMMCGhvbWVhd2F5MRwwGgYJKoZIhvcNAQkBFg1p bmzvqg9rdgeuy29tmb4xdteymdmxote5mtyyofoxdtqymdmxote5mtcyofowgzaxczajbgnvbayt AlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQ0wCwYDVQQK DARPa3RhMRQwEgYDVQQLDAtTU09Qcm92aWRlcjERMA8GA1UEAwwIaG9tZWF3YXkxHDAaBgkqhkiG 9w0BCQEWDWluZm9Ab2t0YS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAOpYZr53pn3n RMseh5XQes/vl604M70D32evHIhMy9vYMdhH64LxlnxP0/pp4DtxxiyNSXgxm/OETNf0c17On9II Sq3TMG7jteAQ3Kan5O4O3tlySy2TcVnWTrN7ZSa60H0SmEUE4mU4YllgXdwuY/1hVxbcXSMyVfCq 3XRpnlIxAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEANartWhK+pd9woN2ln2szaZ9Roa4ccaQB8I1Q ipqpqf74/1pc8nixhdboi5tunhmcl7azsixiywtpoh2/gdsvgtbwi7hdjayian3uxrknhudlcqe1 zmz9x1icd/mkok2qelbfjklbn8eyjvtuebqv7csdsjgglqymdxefjodyyp0= </ds:x509certificate> </ds:x509data> </ds:keyinfo> </ds:signature> <saml2p:status xmlns:saml2p="urn:oasis:names:tc:saml:2.0:protocol"> <saml2p:statuscode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> </saml2p:status> <saml2:assertion xmlns:saml2="urn:oasis:names:tc:saml:2.0:assertion" xmlns:xs=" ID="id "IssueInstant=" T20:50:56.659Z" Version="2.0"> <saml2:issuer xmlns:saml2="urn:oasis:names:tc:saml:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid format:entity"> <ds:signature xmlns:ds=" <ds:signedinfo> <ds:canonicalizationmethod Algorithm=" exc c14n#"/> <ds:signaturemethod Algorithm=" sha1"/> <ds:reference URI="#id "> <ds:transforms> <ds:transform Algorithm=" signature"/> <ds:transform Algorithm=" exc c14n#"> <ec:inclusivenamespaces xmlns:ec=" exc c14n#" PrefixList="xs"/> </ds:transform>

16 16 </ds:transforms> <ds:digestmethod Algorithm=" <ds:digestvalue>luojcqquwzpb2gbsg4lxfdnwy3o=</ds:digestvalue> </ds:reference> </ds:signedinfo> <ds:signaturevalue> cbnqxm/ey/yklqujwizsebz8rcwbs7vxsfazu/ke7b+asqqzob5mcubml5isywtg3+nux+yy8tw4qfbwhmclq3mka4ax 2uAmYzAa8HaL1hDL2rGmv+YOhzN0/l88VmF3sApiSeTeYIwVLhew4nayHktSa4ALMJGDEjK0s3RI4+s= </ds:signaturevalue> <ds:keyinfo> <ds:x509data> <ds:x509certificate> MIICmzCCAgSgAwIBAgIGATYsZIyyMA0GCSqGSIb3DQEBBQUAMIGQMQswCQYDVQQGEwJVUzETMBEG A1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU MBIGA1UECwwLU1NPUHJvdmlkZXIxETAPBgNVBAMMCGhvbWVhd2F5MRwwGgYJKoZIhvcNAQkBFg1p bmzvqg9rdgeuy29tmb4xdteymdmxote5mtyyofoxdtqymdmxote5mtcyofowgzaxczajbgnvbayt AlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQ0wCwYDVQQK DARPa3RhMRQwEgYDVQQLDAtTU09Qcm92aWRlcjERMA8GA1UEAwwIaG9tZWF3YXkxHDAaBgkqhkiG 9w0BCQEWDWluZm9Ab2t0YS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAOpYZr53pn3n RMseh5XQes/vl604M70D32evHIhMy9vYMdhH64LxlnxP0/pp4DtxxiyNSXgxm/OETNf0c17On9II Sq3TMG7jteAQ3Kan5O4O3tlySy2TcVnWTrN7ZSa60H0SmEUE4mU4YllgXdwuY/1hVxbcXSMyVfCq 3XRpnlIxAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEANartWhK+pd9woN2ln2szaZ9Roa4ccaQB8I1Q ipqpqf74/1pc8nixhdboi5tunhmcl7azsixiywtpoh2/gdsvgtbwi7hdjayian3uxrknhudlcqe1 zmz9x1icd/mkok2qelbfjklbn8eyjvtuebqv7csdsjgglqymdxefjodyyp0= </ds:x509certificate> </ds:x509data> </ds:keyinfo> </ds:signature> <saml2:subject xmlns:saml2="urn:oasis:names:tc:saml:2.0:assertion"> <saml2:nameid Format="urn:oasis:names:tc:SAML:2.0:nameid <saml2:subjectconfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml2:subjectconfirmationdata NotOnOrAfter=" T20:55:56.659Z" Recipient=" </saml2:subjectconfirmation> </saml2:subject> <saml2:conditions xmlns:saml2="urn:oasis:names:tc:saml:2.0:assertion" NotBefore=" T20:45:56.659Z" NotOnOrAfter=" T20:55:56.659Z"> <saml2:audiencerestriction> <saml2:audience> </saml2:audiencerestriction> </saml2:conditions> <saml2:authnstatement xmlns:saml2="urn:oasis:names:tc:saml:2.0:assertion" AuthnInstant=" T20:50:56.659Z"SessionIndex="id "> <saml2:authncontext> <saml2:authncontextclassref> urn:oasis:names:tc:saml:2.0:ac:classes:passwordprotectedtransport </saml2:authncontextclassref> </saml2:authncontext> </saml2:authnstatement> <saml2:attributestatement xmlns:saml2="urn:oasis:names:tc:saml:2.0:assertion"> <saml2:attribute Name=" Address" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname format:unspecified"> <saml2:attributevalue xmlns:xs=" xmlns:xsi=" e> </saml2:attribute> </saml2:attributestatement> </saml2:assertion> </saml2p:response>

17 Appendix B SAML: Assertion Supported Claims Required Attributes: Persistent ID : This can be described as the attribute that is least likely to change for an identity. Smartsheet accepts six formats (a few of them are not specified in the SAML 2.0 standard) encoded in the NameID element. Here are the formats we support: urn:oasis:names:tc:saml:1.1:nameid format: address urn:oasis:names:tc:saml:2.0:nameid format: urn:oasis:names:tc:saml:2.0:nameid format:persistent urn:oasis:names:tc:saml:2.0:nameid format:unspecified urn:oasis:names:tc:saml:1.1:nameid format:unspecified urn:oid: Smartsheet will also accept assertions without a NameID element and will extract a Persistent ID value from an attribute if there is an attribute that matches the following: name="edupersonprincipalname" nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" name=" name="persistent" nameformat="urn:oasis:names:tc:saml:2.0:nameid format:persistent" name="urn:oid: " nameformat="urn:oasis:names:tc:saml:2.0:attrname format:uri" name="edupersonprincipalname" nameformat="urn:oasis:names:tc:saml:2.0:attrname format:uri" address: This is the address associated with the Smartsheet account. This equates to a username in the Smartsheet service. This must be an attribute and will not be extracted from the NameID element. Here are the accepted formats: name=" " name=" name=" address",nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" name=" address",nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" name=" ",nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" name="saml_username",nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" name=" address",nameformat="urn:oasis:names:tc:saml:2.0:attrname format:unspecified" 17

18 name=" address",nameformat="urn:oasis:names:tc:saml:2.0:attrname format:unspecified" name=" address",nameformat=" name="urn:oid: ",nameformat="urn:oasis:names:tc:saml:2.0:attrname format:uri" name="mail",nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" Optional Attributes Given Name: The given name of the user associated with the account (first name). Here are the formats that Smartsheet supports: name="givenname" name=" name="givenname" nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" name="given_name" nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" name="givenname" nameformat=" name="givenname" nameformat="urn:oasis:names:tc:saml:2.0:attrname format:unspecified" name="urn:oid: " nameformat="urn:oasis:names:tc:saml:2.0:attrname format:uri" Surname: The surname of the user associated with the account (last name). Here are the formats that Smartsheet supports: name="surname" name=" name="surname" nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" name="sur_name" nameformat="urn:oasis:names:tc:saml:2.0:attrname format:basic" name="surname" nameformat=" name="surname" nameformat="urn:oasis:names:tc:saml:2.0:attrname format:unspecified" name="urn:oid: " nameformat="urn:oasis:names:tc:saml:2.0:attrname format:uri" 18