Partner API
API Reference

Single Sign On for retailers

Epsilon Retail Media's SSO integration allows direct connection to a retailer's IDP via SAML 2.0. You will be able to provide your retailer users the ability to log in via SSO, authenticated via your IDP.

📘

Retailer users only

As a multi-tenant platform that enables advertisers to access multiple retailer platforms, our capability is best suited to retailers looking to enforce SSO for internal staff, not advertisers.

We do not enable delegated authority of an advertiser user's lifecycle, as this can impact other retailer platforms.

Scope of Capability

Epsilon Retail Media allows your IDP to authenticate if the user has access to your namespace. This is configured on a per-namespace basis. Please note that the SSO capability in the platform enables authentication, not authorisation. Team access management is still programmatically configured within the platform.

📘

Advertiser access

As our platform is a multi-tenancy platform that is globally connected; advertisers will still log in directly via the login module. Advertisers will still need to be invited to your platform to gain access, even if they can access other retailer platforms.

Key information

  • This capability is best for retailers wanting to manage internal user lifecycles, for use cases such as secure offboarding for internal staff members
  • Team and user access must be programmatically managed within the platform and is not possible via the SSO integration
  • All IDP user support and management is to be managed by the retailer.
  • Advertiser user lifecycles must remain within the Epsilon platform. We do not provide delegated authority to offboard advertiser users, as this can impact other platform access for the advertiser.

User flows

The flows are different for both existing and new platform users.

Existing user flow

If you are implementing SSO post-launch, most users will already have access to teams, and have accounts set up in Epsilon. Therefore, the flow is simpler.


New user flow

For new users, you will need to invite each user to the relevant teams. They should undergo the sign-up process, and then can authenticate via your SSO IDP for future access.

If required, they can also sign in directly via your SSO IDP, and we will create a user just in time once the authentication is approved. The user will still need to be manually invited to their relevant teams programmatically. Our recommendation is to invite users prior, to ensure their team access is configured.


User experience

In portals with retailer SSO integrated, the password field is removed from the initial sign-in screen. If a user enters an email that is connected to your IDP under your retailer domain, then the user is automatically forwarded to your IDP for authentication.

The forgot password function is also delegated to the password entry on the next step, as you are responsible for any SSO related password management.

Integration requirements

IDP integration

To integrate, Epsilon requires the below:

From your IDP

  • Entity ID
  • SSO URL
  • IDP Signature Certificate

We also require the below:

  • Custom login help link: this link will be shown to all users, where you will need to host a link explaining the process to sign in
  • Custom message: custom message shown related to the custom link
  • Custom link label: label for the custom login help link
  • Password reset website name: website name shown to users
  • Expired password URL: where your IDP will forward your password expiry links

Epsilon will also configure on the Epsilon side the below information that will be shared with you:

  • Entity ID (audience URI)
  • Base URL
  • ACS URL

These will be provided by the Epsilon team.

Mapping attributes

Attributes on the Epsilon configuration are as below:

  • primary email
  • firstName
  • lastName
  • email

You may need to configure mappings in your IDP accordingly.

Unsupported SSO Functionality

User Provisioning/De-provisioning: Due to the technical configuration of user teams within Epsilon the ability to easily add, manage, and remove users within teams without requiring manual intervention in both the Identify Provider (IDP) and the Epsilon platform.

User Account Configuration & Support: User account management and support is not provided by Epsilon when a retailer migrates to SSO. Epsilon will remove the direct login option, and the password reset link, and all SSO users will be redirected back to the retailer for user management support.

Retailer Owned Platform SSO: Advertiser Account Workaround

If you are a retailer integrating our partner API capabilities and providing advertisers your own front-end, we have a workaround offered to retailers that enables you to manage advertiser lifecycles within your own portals.

The purpose of this capability is also to enable your owned platform to automatically authenticate with Epsilon’s platform within your owned namespace.

High-level overview

This workaround involves leveraging the existing retailer SSO capabilities, by enabling you to create advertiser accounts under your owned domain.

  • Retailer will create the user account within their Identify Provider (IDP) service. Utilising the Epsilon OKTA just in time (JIT) provisioning, this will automatically provision the user account within the Epsilon platform.
  • The retailer will invite the user to the required supplier or retailer team through the Epsilon team management UI. (Without this the user will be presented with a blank UI in Epsilon)
  • The user account must have a unique domain name specified by the retailer. Multiple domain names may be configured within OKTA such as name@retailer.com, name@retailerdomain.com, name@retailername.com

Deprovisioning

Deprovisioning of users will be the following process:

  • The retailer will deprovision the user account in the IDP.
  • The user will not be able to authenticate/login to the Epsilon platform under the retailer’s owned user email.
    • The user will still be able to authenticate/login to other retailer platforms with their regular advertiser email
  • The user account will still exist within Epsilon however after 90 days of inactivity the Life Cycle Management process will deactivate their account.
  • If the user account is reactivated within the IDP the corresponding user account within Epsilon will also be activated.
  • If the retailer requires that the user is completely removed from Epsilon they must be manually removed from the team(s) they were invited to within the platform.

Limitations

  • This does not maintain the real advertiser’s account lifecycle, and instead creates a duplicated isolated user for the advertiser underneath your retailer domain. This creates potential confusion for the advertiser.\
  • This workaround maintains the same limitations outlined within the Unsupported SSO Functionality section, wherein the retailer will need to manage account configuration, support, and user/team access.
  • All user support and management is to be managed by the retailer.

FAQs

  • What happens if I don’t invite someone to their teams but they sign in via SSO?
    • If the user doesn’t exist, but signs in via SSO, they will be met with a blank screen until you have invited them to teams.
  • Is there any way to manage team/user access by SSO or API?
    • No, this is not currently possible and needs to be handled programmatically via the UI.