Configure your partner account to use Single Sign On (SSO).

Approved Constant Contact technology partners reselling Constant Contact accounts under their partner account can integrate with Constant Contact’s Single Sign On (SSO) solution. SSO uses SAML 2.0 standards and allows a users under a partner’s managed client account to access their integrated Constant Contact account without having to sign in with a separate username and password.

Please contact your Constant Contact partner account manager to start the process required for setting up and testing SSO. An API support engineer will assist you with setting up SSO.

Roles

Service Provider (SP) - Constant Contact provides access to users of partner-managed Constant Contact client accounts.
Identity Provider (IdP) - The Constant Contact Partner responsible for user authentication and authorization.

SSO Implementation Types

Identity Provider Initiated SSO - also known as Unsolicited Web SSO, the Federation process is initiated by the IdP (Partner account), sending an unsolicited SAML Response to the SP (Constant Contact).
Service Provider Initiated SSO - the SP (Constant Contact) generates an AuthnRequest that is sent to the IdP (Partner account) as the first step in the Federation process. Next, and the IdP responds with a SAML Response.

Authentication

Constant Contact’s SSO implementation uses Identity Provider (IdP) initiated SSO, meaning the initial user interaction is performed by the IdP (the Partner) and not by the SP (Constant Contact).

The Constant Contact SSO authentication sequence of events is as follows:

A user under a partner’s managed client account authenticates with the Partner. By default, only the Account Owner user in a partner-managed client account can use SSO. To allow all users under a partner-managed client account to use SSO, the partner account must first have the SSO for All Users feature enabled. This feature must be enabled by your Constant Contact partner account manager or support engineer.
The Partner issues a response to Constant Contact with the required user attributes.
Constant Contact processes the response from the Partner.
Constant Contact grants or denies the user access.

sso_diagram

SAML Response Requirements

The Partner account makes SAML posts to the following Constant Contact SP URL: https://identity.constantcontact.com/sso/saml2?RelayState=https://login.{env}.constantcontact.com/login/idp-redirect

Where {env} defines the environment to differentiate between pre-production testing and production environments. Constant Contact provides you with the complete URL.

The Partner identifies itself to Constant Contact using a SAML2 response. The digitally signed XML response must include the following elements.

/Response:Destination - the Assertion Consumer Service URL that Constant Contact provides. For example: http://{env}.identity.constantcontact.com/sso/saml2
/Response/Issuer - the entity identifier of the IdP, a string that you (the Partner) provide to Constant Contact. This is usually the partner name.
/Response/Assertion/Issuer - The entity identifier of the IdP within the Assertion body.
/Response/Assertion/Subject/NameID - Identifier for the authenticated principal (the external user ID that was generated when you created the Constant Contact Technology Partner client account). Transient identifiers are not supported.
Signing certificates - The SAML2 response must be digitally signed using a private key. The partner IdP needs to provide Constant Contact with the digital certificate/public key of the private/public key pair used to sign the SAML response. The IdP needs to provide Base64 encoded X.509 certificates for pre-production and production environments, along with their expiration dates.

Sample Certificate

Add a New User to an existing SSO-Enabled Client Account

To add a new SSO user to an existing SSO-enabled client account, make a POST call to the /partner/accounts/{encoded_account_id}/users/sso endpoint.

Request parameters

Use the encoded_account_id path parameter to identify the client account to create the user under.
Use the request body properties that follow to create the new user (all request body properties are required).
- first_name : The client account user’s first name. For example: Josie.
- last_name : The client account user’s last name. For example: Lang.
- role_name : The client account user role. User roles include: account_manager or campaign_creator.
- contact_email : The unique email address to associate with the user in the client account. For example: josie.lang@gmail.com.
- login_name : The unique account login name to associate with the client account. For example: josie_lang.
- external_id : The ID that uniquely identifies the client account for the external authenticator. For example: 21378234122161121.
- external_provider: The name of the external authenticator. For example: Google.

Example Requests

The following are example POST /partner/accounts/{encoded_account_id}/users/sso requests:

JAVA cURL PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://partner/accounts/{encoded_account_id}/users/sso',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
   "contact_email": "josie_lang@gmail.com",
   "login_name": "josie_lang",
   "external_id": "33378234122161121",
   "external_provider": "google",
   "last_name": "lang",
   "first_name": "josie",
   "role_name": "campaign_creator"
}',
  CURLOPT_HTTPHEADER => array(
    'x-api-key: {x-api-key}',
    'Content-Type: application/json',
    'Authorization: Bearer {access_token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

curl --location 'https://partner/accounts/{encoded_account_id}/users/sso' \
--header 'x-api-key:{x-api-key}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
   "contact_email": "josie_lang@gmail.com",
   "login_name": "josie_lang",
   "external_id": "33378234122161121",
   "external_provider": "google",
   "first_name": "josie",
   "last_name": "lang",
   "role_name": "campaign_creator"
}'

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, "{\n   \"contact_email\": \"josie_lang@gmail.com\",\n   \"login_name\": \"josie_lang\",\n   \"external_id\": \"33378234122161121\",\n   \"external_provider\": \"google\",\n   \"first_name\": \"josie\",\n   \"last_name\": \"lang\",\n   \"role_name\": \"campaign_creator\"\n}");
        Request request = new Request.Builder()
        .url("https://partner/accounts/{encoded_account_id}/users/sso")
        .method("POST", body)
        .addHeader("x-api-key", "{x-api-key}")
        .addHeader("Content-Type", "application/json")
        .addHeader("Authorization", "Bearer {access_token}")
        .build();
        Response response = client.newCall(request).execute();

Sample Response

A 201 response message and the new user’s details are returned after the user is successfully created under the specified partner client account. The following example shows user details returned in the response body.

{
   "first_name": "josie",
   "last_name": "lang",
   "role_name": "campaign_creator",
   "contact_email": "josie.lang@gmail.com",
   "login_name": "josie.lang",
   "user_uuid": "3g158fb8-abb3-45e1-a783-dcdb7093e956",
   "external_id": "33378234122161121",
   "external_provider": "google"
}

Response Codes

API errors are identified using standard HTTP response codes in a JSON-formatted error message array.

201: The user was successfully created under the client partner account.
400: Bad request. Either the JSON was malformed or there was a data validation error. For example, the request may include bad data. For example, you do not include a required property in the request body.
401: Unauthorized. For example, authentication fails.
403: Forbidden. For example, if you are try to create a user in the client account and not under the partner account.
409: Conflict. A resource with that name already exists. For example, if the contact_email or external_id already exists.
500: Internal service: There was a problem with our internal service.

View it! Although technology partner endpoints cannot be tested using our API Reference tester, response samples and schema are available for this endpoint.

Tags: Technology_Partners SSO

Configuring Identity Provider (IdP) Initiated SSO