A SAML SSO is a desired add-on to the CampaignDrive platform because it provides a more secure login experience from an IT perspective and it allows your End Users to log in from your company intranet, meaning one less password to remember.
Overview
Single Sign On (SSO) enables customers to grant their users access to CampaignDrive from a link on the customer’s corporate site. Users log into the corporate site with their existing corporate username and password and are granted access to CampaignDrive. Users never directly log into CampaignDrive and authentication is always maintained by the customer/brand. When access is granted to CampaignDrive, certain user information is passed to CampaignDrive and will govern the user’s experience in CampaignDrive (user information is also referred to as user’s attributes). For the exchange of user information between the two parties CampaignDrive implements the Security Assertion Markup Language (SAML) 2.0 protocol.
Who Should Read This Document?
This document is directed at the development IT team or the implementation specialist who would implement the SSO connection. Marketing personnel and project sponsors would also gain from reading this document; however, some of the information is of a technical nature and would require expert knowledge.
Who Should Use SSO
CampaignDrive SSO is for customers who want to centralize user access management and already store user access credentials (name, password) in their corporate infrastructure. It is only suited for customers who can adhere to the SAML 2.0 protocol and can map certain user attributes and pass them to CampaignDrive when a user logs in.
Features
- Automatic creation/update of a user’s name, email, role and location associations upon login
- Ability to override the automatic update of role assignments, locations and location group associations
- Full control of authentication by the customer on their corporate site
- Support Identity Provider (IdP) and Service Provider (SP) initiated login and for controlled security
- Support login from different sources (by allowing multiple certs)
Implementation Requirements
CampaignDrive SSO supports any SAML 2.0-compliant IdP (such as Windows Active Directory with ADFS, Shibboleth, OneLogin, Okta or Ping), and administrators of those systems must have the ability to map certain attributes from their organization directory and pass them in a SAML assertion. Those attributes will govern some of the user experience in CampaignDrive.
Attributes Passed from the IdP in the SAML Assertion
The ‘CampaignDrive SSO User Attributes’ table lists supported attributes.
All attributes are case-sensitive, and attributes marked "Required" must be passed as described in this table. (All other attributes can be optionally passed.)
CampaignDrive SSO User Attributes
Attribute Name |
Attribute Value/Description |
Required? |
|
Identifier |
A unique string that is associated with a single user. The Identifier makes it possible to create the user record, address it, or update it. For example, the Identifier might be the user’s corporate email address or the user’s corporate ID. |
Yes |
|
FirstName |
The user’s first name, provided as a string. This can't be an empty string. |
Yes |
|
LastName |
The user’s last name, provided as a string. This can't be an empty string. |
Yes |
|
EmailAddress |
The user’s email address, provided as a string. |
No |
|
Role |
The role that the user will assume in CampaignDrive. Roles (role names) are of type strings and must exist in CampaignDrive prior to being passed. If the role attribute is not passed, the user is automatically assigned the ‘Normal User’ role. |
No |
|
Locations |
An array (list) of 1 or more location identifiers. When a user logs in to CampaignDrive, the user will be associated (and have access) to these locations. A location must first exist in CampaignDrive prior to passing its identifier. In addition to passing location identifiers, the asterisk symbol (‘*’) can be passed in order to associate a user with all active locations (Note: When CampaignDrive is configured for multiple brands, this will associate to all locations regardless of brands, i.e., segregation by brands is not supported.) |
Yes, if LocationGroups is absent |
|
LocationGroups |
An array (list) of 1 or more location group identifiers. When a user logs in to CampaignDrive, the user will be associated (and have access) to these location groups. A location group must first exist in CampaignDrive prior to passing its identifier. |
Yes if Locations is absent |
See examples here for how attributes should be formatted in a SAMLResponse. (Note that the support for encrypted assertions is unstable, hence the usage of it is discouraged.)
Other Technical Requirements
- In order to configure an IdP-initiated SSO, a client needs to:
1.1. know that the ACS URL is "https://<customer-name>.pica9.com/cd/login/auth-service-verify" or
"https://<customer-name>.pica9.com/cd/login/auth-service-verify?key=<cd-saml-config-key>"
1.2. know that the SP Entity Id is "http://saml.pica9.com/cd"
1.3. provide self-signed 2048-bit X.509 public key certificate with the digest algorithm: sha1 or sha256
1.4. make sure that NameID is specified in the SAML assertion
2. In order to configure an SP-initiated SSO, a client needs to:
2.1. see 1.1.
2.2. see 1.2.
2.3. see 1.3.
2.4. see 1.4.
2.5. know that the SSO initiate URL is https://<customer-name>.pica9.com/cd/login/auth-service
2.6. provide the IDP Sign-in URL (SSO URL)
2.7. provide the IDP Entity ID
Configuring Updates to Roles, Locations, and Location Groups
Roles, location and location groups can be configured such that subsequent user logins will not automatically update the role, locations or location groups for a user. When a user first logs in these values will be used in creating the user (a new user); however, updates on subsequent login are configurable. This lets System Administrators update the role, locations, and locations groups in CampaignDrive (but let users log in initially). This is a system-wide configuration set by a Pica9 representative and can not be set on a user-by-user basis. Contact your CampaignDrive Customer Success Manager for information about changing the default.
Multiple Login Sources
CampaignDrive can support multiple Identity Providers each initiating the login process using a different certification. For example, a client might initiate login from Okta using one cert for the SAML assertion and also use the corporate's SAML service using a different cert. In order to use multiple sources clients must supply the 'key' parameter in the query string when posting the assertion. In addition to the requirements listed in 'Other Technical Requirements', clients will must add a 'key' parameter to the endpoint.
|
SSO Configuration Requirements |
Description |
|
https://<customer-name>.pica9.com/cd/login/auth-service-verify?key=<key-name> |
The endpoint for sending the assertion. Adding the `key' parameter would search for a specific certificate in CamapaignDrive. The key parameter can only be composed of alpha characters. Example: https://brand.pica9.com/cd/login/auth-service-verify?key=mydivision |
Note: A Pica9 representative will need the 'key' value and the additional certificate. The backend configuration must be in place to enable the additional login source(s).
Notes
- Deactivation of users within CampaignDrive would prevent a user from logging in via the SSO.
Appendix
Login flow 'IdP' initiated
Login flow 'SP' initiated
The end-user starts by clicking on a link on the client's intranet, which redirects them to https://<customer-name>.pica9.com/cd/login/auth-service.
When requested, the /cd/login/auth-service endpoint initiates a SAMLRequest and sends it to the SSO URL configured on the /cd/saml-config/edit/idp/<configuration> page.
On receiving the SAMLRequest, the IDP (maintained by client) looks up the info of the currently logged-in user and sends a SAMLResponse with the mapped value to /cd/login/auth-service-verify. If no user is currently logged in, the IDP will try to log a user in by methods that can be specified by the SAMLRequest and or the IDP's internal configuration. Examples of such login methods include Integrated Windows Authentication (IWA) and Password Authentication.
The rest of the workflow is virtually the same as an IDP-initiated workflow. Notice the last step was the IDP initiating a SAMLResponse to the receiving CD endpoint.
