Single Sign-On (SSO) Using SAML

V.2.3 AS OF 2016-11-03

Please visit SAML SSO section in SCU for additional information

OVERVIEW

ServiceChannel offers a full featured Single Sign On (SSO) system to improve the security of your team’s access to ServiceChannel while making it easier for them to gain access. Our SSO system allows your users to login once, in your system, and then access ServiceChannel as the correct user account with correct permissions without the need to login again.

Today ServiceChannel supports SAML SSO - an enterprise solution for single sign on supported by all major 3rd party vendors and tools such as ADFS, SiteMinder, Okta, Ping One/Federate/Identity. In general, SAML SSO is a system level integration where parameters are discussed ahead of time, and are passed through an assertion. The assertion can be encrypted and signed and ServiceChannel will validate the assertion and login the user to the appropriate application. New users can be created on the fly if the required fields are available in the assertion.

ServiceChannel supports Identity Provider Initiated SAML SSO. We do not currently support Service Provider Initiated SAML SSO.

See also: https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language.

This memo describes all the details needed to complete such integration.

2

SAML SSO CONCEPTS

Step 1: User authenticates with (logs in to) Identity Provider system (ADFS, SiteMinder, PingFederate, etc)

Step 2: Identity Provider system sends SAML Assertion to Service Provider system (ServiceChannel)

Step 3: Service Provider system (ServiceChannel) validates data provided in SAML Assertion, activates a logged in session, and provides user access to the logged in session with their user’s access permissions

3

USER FEED CONCEPTS

Note: User Feed is not required for SAML SSO, but we recommend it as a best practice.

There are several options to create user accounts in ServiceChannel: ● Manually via UI ● Using User Feed templates (this option is recommended) ● Using SAML SSO with Just-in-Time Provisioning

Regardless the way selected to create user accounts, we highly recommend to use e-mail address as a user identifier in ServiceChannel instead of user name (e.g. JohnDoe@yourcompany.com instead of JohnDoe) to ensure uniqueness of your user identifiers.

The following data is provided in a User Feed Template: ● Subscriber ID ● User name ● Email address ● Userid ● Password (should be empty if you are going to limit your user to SSO logins only) ● Locations / districts / regions this user should have an access to ● Role ● NTE, proposal approval and invoice approval limits ● status (active / inactive)

A User Feed Template can be uploaded into ServiceChannel once during initial setup or on a regular basis. Your ServiceChannel SSO Implementation manager will supply a copy of the User Feed template. We recommend automating the process nightly by having an application on your system create a list of all your users that will need access to ServiceChannel in the standard User Feed template format and upload the file to the ServiceChannel servers for processing.

4

SAML SSO IMPLEMENTATION ROADMAP

Items To Clarify Before Implementation

● Is SAML going to be used for authentication only? ● Should users be created/managed through SAML assertions or User Feed? ● Do you want users to be redirected to some specific page after logging off from ServiceChannel

portal? Note - we recommend authentication only SAML SSO with a User Feed as the fastest solution to deploy.

Implementation Steps

In general, the following steps should be performed to setup SAML SSO:

1. CLIENT configures connection to ServiceChannel testing environment 2. CLIENT provides Issuer and certificate (optional) to ServiceChannel 3. ServiceChannel configures connection in ServiceChannel testing environment 4. ServiceChannel will provide notice to CLIENT team that the connection is ready for testing 5. CLIENT will test connection with 2 to 3 users to confirm access is granted and person is logged in as

correct user 6. CLIENT will alert ServiceChannel that connection is working well and can be deployed into production 7. CLIENT will select the day and time the connection can be deployed into production 8. ServiceChannel team will deploy connection configuration into production environment at the

selected day and time

Data required to configure SAML SSO connections

● On the CLIENT side - ServiceChannel Certificate (see Appendix A) and end points ○ Production: https://login.servicechannel.com/saml/acs ○ Testing: https://st1login.servicechannel.com/saml/acs

● On ServiceChannel side - CLIENT certificate and Issuer value from SAML assertions.

5

DATA TO BE PROVIDED IN SAML ASSERTIONS

ServiceChannel will expect the following information passed in assertions:

Field Required? Field explanation

NameID Required User ID in SC. Should be in Subject section of SAML assertion.

Name Optional User name.

Email Optional User e-mail address.

Role Optional User Role as defined in uploaded User Role template.

Location Optional Org Unit for the user - Location / Store ID, comma separated list. User will have an access to all locations if this field is not provided.

Region Optional Org Unit for the user - Region, comma separated list. User will have an access to all regions if this field is not provided.

District Optional Org Unit for the user - District, comma separated list. User will have an access to all districts if this field is not provided.

NTELimit Optional NTE limit value. The current value in SC will remain unchanged if this field is not provided.

ProposalApprovalLimit Optional Approval limit value. The current value in SC will remain unchanged if this field is not provided.

InvoiceApprovalLimit Optional Invoice approval limit. The current value in SC will remain unchanged if this field is not provided.

Currency Optional Currency for limits above. "USD" will be used if this field is not provided.

Only NameID value is required for authentication only SAML SSO.

6

APPENDIX A. SERVICECHANNEL CERTIFICATE

Here is ServiceChannel certificate used with SAML SSO in CRT format:

-----BEGIN CERTIFICATE----- MIIFxjCCBK6gAwIBAgIRANRBXjXH6S4kncyRwWxxRRQwDQYJKoZIhvcNAQELBQAw ejELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAlZBMRAwDgYDVQQHEwdIZXJuZG9uMSEw HwYDVQQKExhOZXR3b3JrIFNvbHV0aW9ucyBMLkwuQy4xKTAnBgNVBAMTIE5ldHdv cmsgU29sdXRpb25zIE9WIFNlcnZlciBDQSAyMB4XDTE1MDQyNzAwMDAwMFoXDTE4 MDcyNjIzNTk1OVowgckxCzAJBgNVBAYTAlVTMQ4wDAYDVQQREwUxMTUwNzELMAkG A1UECBMCTlkxEjAQBgNVBAcTCUFsYmVydHNvbjEYMBYGA1UECRMPOSBBbGJlcnRz b24gQXZlMSAwHgYDVQQKExdTZXJ2aWNlY2hhbm5lbC5jb20uIEluYzELMAkGA1UE CxMCSVQxITAfBgNVBAsTGFNlY3VyZSBMaW5rIFNTTCBXaWxkY2FyZDEdMBsGA1UE AxQUKi5zZXJ2aWNlY2hhbm5lbC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw ggEKAoIBAQDV71NLtz7rj+fSHvCRGD01CHU6TCgrlnNTiW7PT2yWehMTqhBLUNja Z7mpi3ZyDGYlx+t+q7C07nDiKwyZ4TA5tmdvtXmtkPUlZDlxQPV8swWUikSyI5lG tPv8NSqj908/ZTr3e3/9107OB8pmHfuIJDpTi8wW6Tt+MauzKzA9CXKRKF5CVGVh iSq5akvoQiBEhGHDUxexE8novhA393HMfyNAKIP57+W/KRcofeBVlmC1itVUaUuX 5ZGpWlHmz2xvxI1gAol1JaGt61PAMDClbQVrZ7UMB9O3lO9rmisvr2f1NHnO0XFS 6Vf2/vTR+egr0uIlbT2IYL4tgDIUS4JhAgMBAAGjggH1MIIB8TAfBgNVHSMEGDAW gBQgM823Yfalhk/cyddzarwKUWWY7DAdBgNVHQ4EFgQUQTFBRZ3OUqQWN3NlKGdI VEBF15UwDgYDVR0PAQH/BAQDAgWgMAwGA1UdEwEB/wQCMAAwHQYDVR0lBBYwFAYI KwYBBQUHAwEGCCsGAQUFBwMCMHUGA1UdIARuMGwwYAYMKwYBBAGGDgECAQMBMFAw TgYIKwYBBQUHAgEWQmh0dHA6Ly93d3cubmV0d29ya3NvbHV0aW9ucy5jb20vbGVn YWwvU1NMLWxlZ2FsLXJlcG9zaXRvcnktY3BzLmpzcDAIBgZngQwBAgIwSQYDVR0f BEIwQDA+oDygOoY4aHR0cDovL2NybC5uZXRzb2xzc2wuY29tL05ldHdvcmtTb2x1 dGlvbnNPVlNlcnZlckNBMi5jcmwwewYIKwYBBQUHAQEEbzBtMEQGCCsGAQUFBzAC hjhodHRwOi8vY3J0Lm5ldHNvbHNzbC5jb20vTmV0d29ya1NvbHV0aW9uc09WU2Vy dmVyQ0EyLmNydDAlBggrBgEFBQcwAYYZaHR0cDovL29jc3AubmV0c29sc3NsLmNv bTAzBgNVHREELDAqghQqLnNlcnZpY2VjaGFubmVsLmNvbYISc2VydmljZWNoYW5u ZWwuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQAjhho6SO6zxHTs4qJCzpFb0GcZoy/P qzKl39eU0HtLD9kZPtIm9AUVmMEaGPsk7h2dM86rvayq0q43itfYy5J/Rw0ckwGd U4SGbrVoKg0FkODSWdY67XYKfMh4rjSDB7m7pFQXyEf7Y913qzVB26rGIneKrYJd gnmyC5lbWCRPzw32exBiuYROB/k0wIEfGskI9hto8Wqq9Iqtt0h/KYOyC2DTiLFi c6V1kReuFb5AZ9rWP5wuO+v99IBtSTytZ9Oy3TOBfb/MtSlU7UnzAh51QJzAg7Z2 XM9kc+A242oX3dAJgoF5XUphQShw3n1tsYYoocWcUOHz9H2WBNMuGA88 -----END CERTIFICATE-----

7

APPENDIX B. SAML ASSERTION SAMPLES

Authorization only SSO

Here is a sample of SAML assertion for a authorization only SSO (most important fields - Issuer and NameID - are highlighted):

<samlp:Response ID="_abcd4562-aabb-435f-bcdf-543575354535" Version="2.0" IssueInstant="2016-04-12T20:14:25.281Z" Destination="https://st1login.servicechannel.com/saml/acs" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">

<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://adfs.mydomain.com/adfs/services/trust</Issuer>

<samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"

/> </samlp:Status> <Assertion ID="_abcd4562-aabb-435f-bcdf-543575354535"

IssueInstant="2016-04-12T20:14:25.281Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">

<Issuer>http://adfs.mydomain.com/adfs/services/trust</Issuer> <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

some-values-here </ds:Signature> <Subject>

<NameID>user_name_here@mydomain.com</NameID> <SubjectConfirmation

Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <SubjectConfirmationData

NotOnOrAfter="2016-04-12T20:19:25.281Z" Recipient="https://st1login.servicechannel.com/saml/acs" />

</SubjectConfirmation> </Subject> <Conditions NotBefore="2016-04-12T20:14:25.277Z"

NotOnOrAfter="2016-04-12T21:14:25.277Z"> <AudienceRestriction>

<Audience>https://st1login.servicechannel.com/saml/acs</Audience> </AudienceRestriction>

</Conditions> <AuthnStatement AuthnInstant="2016-04-12T20:14:25.256Z"

SessionIndex="_abcd4562-aabb-435f-bcdf-543575354535"> <AuthnContext>

<AuthnContextClassRef>urn:federation:authentication:windows</AuthnContextClassRef>

</AuthnContext> </AuthnStatement>

8

</Assertion> </samlp:Response>

Just-in-Time Provisioning SSO

Here is a sample of SAML assertion for a Just-in-Time Provisioning only SSO. Important fields are highlighted, Issuer and NameID are required, Region / District / Location and Role are optional and used if you need to restrict user access to some specific locations:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_abcd4562-aabb-435f-bcdf-543575354535" Version="2.0" IssueInstant="2015-12-16T17:23:50.347Z" Destination="https://st1login.servicechannel.com/saml/acs" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified">

<saml:Issuer>http://adfs.mydomain.net/adfs/services/trust</saml:Issuer> <samlp:Status>

<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>

</samlp:Status> <saml:Assertion ID="_abcd4562-aabb-435f-bcdf-543575354535"

IssueInstant="2015-12-16T17:23:50.347Z" Version="2.0">

<saml:Issuer>http://adfs.mydomain.net/adfs/services/trust</saml:Issuer> <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

some-values-here </ds:Signature> <saml:Subject>

<saml:NameID>user_name_here@mydomain.net</saml:NameID> <saml:SubjectConfirmation

Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml:SubjectConfirmationData

NotOnOrAfter="2015-12-16T17:28:50.347Z" Recipient="https://st1login.servicechannel.com/saml/acs"/>

</saml:SubjectConfirmation> </saml:Subject> <saml:Conditions NotBefore="2015-12-16T17:23:50.331Z"

NotOnOrAfter="2015-12-16T18:23:50.331Z"> <saml:AudienceRestriction>

<saml:Audience>https://st1login.servicechannel.com/saml/acs</saml:Audience> </saml:AudienceRestriction>

</saml:Conditions> <saml:AttributeStatement>

<saml:Attribute Name="Name">

<saml:AttributeValue>user_name_here</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="Email">

<saml:AttributeValue>user_name_here@mydomain.net</saml:AttributeValue> </saml:Attribute>

9

<saml:Attribute Name="Location">

<saml:AttributeValue>4155</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="Region">

<saml:AttributeValue>California</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="District">

<saml:AttributeValue>West</saml:AttributeValue> </saml:Attribute>

<saml:Attribute Name="Role">

<saml:AttributeValue>Associate</saml:AttributeValue> </saml:Attribute>

<saml:Attribute Name="NTELimit">

<saml:AttributeValue>3000</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="ProposalApprovalLimit">

<saml:AttributeValue>4000</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="InvoiceApprovalLimit">

<saml:AttributeValue>5000</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="Currency">

<saml:AttributeValue>CAD</saml:AttributeValue> </saml:Attribute>

</saml:AttributeStatement> <saml:AuthnStatement AuthnInstant="2015-12-16T17:23:26.425Z"

SessionIndex="_abcd4562-aabb-435f-bcdf-543575354535"> <saml:AuthnContext>

<AuthnContextClassRef>urn:federation:authentication:windows</AuthnContextClassRef>

</saml:AuthnContext> </saml:AuthnStatement>

</saml:Assertion> </samlp:Response>

10