Configure SAML2 Single Sign-On with Okta

Overview

This guide explains how an Okta administrator and a SmarterSends administrator configure SAML 2.0 single sign-on (SSO) for a SmarterSends account.

Supported features

• Identity Provider-initiated SSO
• Service Provider-initiated SSO
• Just-In-Time user provisioning

For definitions of these features, see the Okta Glossary:
https://help.okta.com/okta_help.htm?type=oie&id=ext_glossary

Prerequisites

Before you begin, make sure that:

• You have a SmarterSends account with administrator access.
• You have an Okta account with permission to add applications and configure SAML.
• You know your SmarterSends subdomain.
• You have chosen the default SmarterSends role and group for users who are not assigned a role or group through SAML.

Subdomain Field

Enter your SmarterSends subdomain. This is the part of your SmarterSends URL before .smartersends.com. For example, if your SmarterSends URL is https://acme.smartersends.com, enter acme. Do not include https://, .smartersends.com, a path, or a trailing slash.

Read this before you enable SAML

Enabling SAML changes sign-in for all users of this SmarterSends account. Users will no longer sign in through the standard username-and-password flow and must access SmarterSends through Okta.

Backup Admin Access

SmarterSends does not provide a standard backup sign-in URL for non-administrator users. If an administrator needs backup access, contact [e-mail] for instructions before enabling SAML.

Configuration steps

Part 1: Add SmarterSends in Okta

1. Sign in to the Okta Admin Console.
2. Go to Applications > Applications.
3. Click Browse App Catalog.
4. Search for SmarterSends.
5. Select SmarterSends and click Add Integration.
6. In the Subdomain field, enter only your SmarterSends subdomain.

  Example: If your account URL is https://acme.smartersends.com, enter acme.

7. Complete the remaining General Settings as required by your organization and continue.

Part 2: Configure the SAML settings in Okta

1. In the Okta Admin Console, go to Applications > Applications > SmarterSends.
2. Open the Sign On tab.
3. In the SAML 2.0 section, click Edit.
4. Set Application Username Format to Email.

5. Configure the group attribute statements used by SmarterSends:

  SSGroups
  Send Okta groups whose names start with SSG-.

  SSRole
  Send the Okta group whose name starts with SSR-.

6. Save the SAML settings.
7. In the SAML 2.0 Metadata details section, copy the Metadata URL.
8. Copy the Issuer value. You will enter this value as the Entity ID in SmarterSends.

Part 3: Configure SAML in SmarterSends

1. Sign in to SmarterSends with an administrator account.
2. Go to Integrations.
3. Enter the following values:

  Single Sign-On Provider
  Select SAML2 with SCIM.

  Default Role
  Select the role assigned to a user when Okta does not send a matching role.

  Default Group
  Select the group assigned to a user when Okta does not send a matching group.

  Metadata URL
  Paste the Metadata URL copied from Okta.

  Entity ID
  Paste the Issuer value copied from Okta.

4. Click Save.

Part 4: Assign users and test SSO

1. In the Okta Admin Console, open Applications > Applications > SmarterSends.
2. Open the Assignments tab.
3. Assign the SmarterSends application to a test user or test group.
4. Test Identity Provider-initiated SSO by opening the SmarterSends tile from the Okta End-User Dashboard.
5. Test Service Provider-initiated SSO by going to:

  https://YOUR_SUBDOMAIN.smartersends.com/login

6. Confirm that the test user can sign in and has the expected SmarterSends role and group.
7. After testing succeeds, assign the application to the remaining users or groups.

Supported SAML Attributes

Name	Value
Common Name	user.firstName + " " + user.lastName
Email	user.email
Phone	user.primaryPhone
Address	user.streetAddress
City	user.city
State	user.state
Zip Code	user.zipCode
Country	user.countryCode
Timezone	user.timezone
department	user.department
SSGroups	Groups starting with "SSG-"
SSRole	Group starting with "SSR-"

Troubleshooting

Users are sent to the wrong SmarterSends account or SSO fails before sign-in

- Verify the Subdomain value in Okta.
- Enter only the portion before .smartersends.com.
- Do not include https://, .smartersends.com, a path, or a trailing slash.

Okta authentication succeeds but SmarterSends rejects the SAML response

- Verify that the Metadata URL in SmarterSends matches the Metadata URL from the Okta application.
- Verify that the Entity ID in SmarterSends matches the Issuer value from Okta.
- Verify that Application Username Format is set to Email.

The user receives the wrong role or group

- Verify that the Okta group names use the SSG- prefix for SmarterSends groups and the SSR- prefix for the SmarterSends role.
- Verify the SSGroups and SSRole group attribute statements in Okta.
- Verify the Default Role and Default Group in SmarterSends.

The SmarterSends tile does not appear for a user

- Verify that the user or one of the user's Okta groups is assigned to the SmarterSends application.

Support

For help with the SmarterSends integration, email [e-mail] or submit a request at:
https://smartersends.zendesk.com/hc/en-us/requests/new