Partner API

Single Sign On

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

Scope of capability

CitrusAd allows your IDP to authenticate if the user has access to your CitrusAd portal. This is configured on a per-namespace basis.

📘

As CitrusAd Is a multi-tenancy platform globally connected; advertisers are still able to log in directly via the login module if their email has an account with CitrusAd on another retailer.

Advertisers will still need to be invited to your platform to gain access, even if they are able to access other retailer platforms.

User experience

When users log into your portal, they will see a “Login with SSO” button in your login module if you are connected via SAML.

If you are connected via a Google or Microsoft IDP, it will display the relevant IDP’s button on the login module.

In the case you want a unique retailer and advertiser SSO, this is possible too. This would be two IDP connections, and two buttons in the interface.

Integration requirements

IDP integration

To integrate, CitrusAd requires the below from your IDP

• Entity ID
• SSO URL
• Idp signature Certificate
CitrusAd will also configure on the CitrusAd side the below information that will be shared with you:
• Entity ID (audience URI)
• Base URL
• ACS URL

These will be provided by your technical account manager.

Mapping attributes

Attributes on the CitrusAd configuration are as below:

• primary email
• firstName
• lastName
• email

You may need to configure mappings in your IDP accordingly.

Creating groups

Inside your IDP you will need to make the relevant access groups to authorise if your users have access to your CitrusAd portal. That group does not need to be shared with CitrusAd, but is how you can govern access to the CitrusAd portal.

Governing team access

To configure a user's access to a team, the team needs to exist within CitrusAd.

CitrusAd utilises SAML Google membership sharing. Your IDP will need to utilise that functionality to be compatible.

When configuring your integration, you will need to add the groups to share to the group membership mapping.

  • The Team Group name must match the team name in CitrusAd
  • The Role Group must match CitrusAd's user roles
    • RETAILER_FULL, SUPPLIER_FULL, RETAILER_REPORT_VIEW and SUPPLIER_REPORT_VIEW are the available configurations

These groups should be prefixed with citrus:.

For example, to access the team Pepsi, with full supplier access, the group name will be citrus:Pepsi/SUPPLIER_FULL.