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 (most common scenario) IdP security certificate expiration and rollover SAML configuration states Additional configuration options 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 (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 6 2. Add CNAME (optional) Smartsheet provides the default SSO URL for your organization, which is a one step link to log in the Smartsheet using this IdP. 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 IdP form, enter the CNAME and click Add. 3. It may take up to one hour for the change to take effect.

7 3. Activate IdP. In the Edit IdP form, click Activate to activate the IdP. The IdP status will change from Inactive to Active, Default. 7

8 8 4. 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.

9 Click Save to save the new setting. 5. You can edit or add additional IdPs at any time by clicking edit configuration next to the SAML checkbox to open the SAML Administration form. 9

10 10

11 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 with an expiring certificate, we recommend the following steps to minimize downtime for your users: 1. Open the SAML Administration form by going to Account Admin Security Controls Authentication: Edit SAML: Edit Configuration 2. In the SAML Administration form, click Edit on the IdP that is about to expire. 3. In the Edit IdP form, click the Edit button next to the IdP Metadata. 4. Update the metadata with your new security certificate information and click Save. It may take up to 10 minutes for the update to take effect. Note: Most Smartsheet organizations use a unique IdP and should follow the steps above. If you are using the same IdP as another Smartsheet organization, and that other organization activated it first, then you will not be able to edit its metadata. The administrator of the other Smartsheet organization should follow the steps above to update the IdP for everyone who is using it. 11

12 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 : Security certificate is expired Inactive : Valid metadata, valid security certificate Active : Valid metadata, valid security certificate, not sharing entity ID with another active IdP on your account, and activated Additional configuration options 1. 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. 2. Activating IdPs: To activate an IdP, make sure that it doesn t have the same entity ID as another active IdP on your account. 3. Adding additional IdPs: While most organizations only need a single active IdP, there is no limit to the number of IdPs you can add. a. Default IdP. If you have more than one active IdP, users logging in via SAML will authenticate against the Default IdP by default. To make an IdP the default, click the Make Default button in the Edit IdP form. 12

13 b. Adding domains to an IdP. If you have more than one Active IdP, you can add domains to an IdP to ensure that users from that domain will authenticate against that IdP. Any users who don t match an added domain will authenticate against the default IdP. i. To add a domain, click the Edit button next to Domains (advanced) in the Edit IdP form. ii.then, type a domain (e.g. contoso.com ) and click Add domain. 13

14 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