Authentication via iframe

  • Updated on Apr 24, 2025
  • 7 minute(s) read
Prev Next

Overview

Blackthorn offers two types of Events embedding and authentication: a community component and iframing.

Embedding via the Blackthorn Events Listing component allows users to add the Lightning Web component to their Community page. The Events Listing component does not use SSO authentication. Instead, the component authorizes the Community user by comparing the logged-in user with the Contact record.

With iframing, you can add an Event or Event Group directly to your website or community. It also allows for additional customization that is unavailable on the Events Listing component and is often used as an alternative in communities.

Authentication relates an external user to a Salesforce Contact and uses a key/value pairing from the Context Key (“Key”) and the SSO/Authorization Token (“Token”).

Now, Events can support dynamic visibility of Events, Event Items (Tickets), Sessions, and more. The process uses only the Contact ID, instead of the entire Salesforce authentication process, to pass the authenticated “user” to the Blackthorn Events app’s iframe.

The two primary uses are as follows:

  • to allow visibility control of Events and related records to different types of Contacts
  • to automatically pre-populate Contact details for registration

Set Up Authentication

Mobile Check-in App

SSO is not supported on the Events Mobile Check-in app.

What is an SSO Code?

An SSO code is an authentication method that enables users to authenticate the Events app securely.

How Iframe Authentication Works

  1. An Attendee logs into a website or a Community that uses iframes.
  2. The Events app pulls the Contact ID.
  3. When the Attendee goes to the iframe, your SSO generation code will run and generates a token.
  4. The SSO generation code then uses the Contact ID from Step 2.

Setup Process

Pre-requisite

The SSO key generator must be dynamic (or be able to take in any Contact ID and spit out an SSO key) to work on multiple Contacts. If you hardcode a Contact ID, authentication will only work for that Contact.

Start Here

To use Blackthorn Events authentication for Salesforce, complete the steps below.

  1. Embed the Events app via iframe.
  2. Generate a Context Key (e.g., Shared Secret) with valid UTG-8 characters using a key generation tool (ex. https://guidgenerator.com/online-guid-generator.aspx).
  3. Encode the Context Key to base64 with an encoding tool.
  4. Send the Context Key and Org ID securely to admin@blackthorn.io if your Events app is live.
    • Blackthorn will respond to your request within 1-3 business days.
    • Do not send the Context Key within cases or to other Blackthorn emails.
    • Send one Context Key per Salesforce org.
  5. Dynamically generate a Token by writing SSO code. The SSO code is the trigger that authenticates a Contact within the Events app.
  6. Your organization is responsible for writing the SSO code and implementing the process. Here is a code sample you can base your code on: ssogenerator.pseudo. The script must be applied to the programming language you are using,, where the codes need to be generated. The Subject ID listed in the pseudocode is the Salesforce Contact ID.
  7. Add the SSO code (data-sso) to the iframe.
<script
  src="https://events.blackthorn.io/loader"
  data-path="/2N9C2F6/g/mfztRPF52q"
  data-sso="XXXXXXXXXXXXXXXXXXXXXXXXX">
  </script>

Using a 3rd-party Open Authentication Protocol

Complete the steps below to use Blackthorn Events authentication with your 3rd-party open authentication protocol (such as OpenID, Okta, etc.).

  1. Embed the Events app via iframe.
  2. Generate a Context Key (e.g., Shared Secret) with valid UTG-8 characters using a key generation tool (ex. https://guidgenerator.com/online-guid-generator.aspx).
  3. Encode the Context Key to base64 with an encoding tool.
  4. Send the Context Key securely to Blackthorn Onboarding or Support if your Events app is live.
    • Blackthorn will respond to your request within 1-3 business days.
    • Do not send the Context Key within cases or to other Blackthorn emails.
    • Send one Context Key per Salesforce org.
  5. Dynamically generate a Token by writing SSO code. The SSO code is the trigger that authenticates a Contact within the Events app.
  6. Your organization is responsible for writing the SSO code and implementing the process. Here is a code sample you can base your code on: ssogenerator.pseudo. The script must be applied to the programming language you are using, where the codes need to be generated. The Subject ID listed in the pseudocode is the Salesforce Contact ID.
  7. Add the SSO code (data-sso) to the iframe.

Visibility Control

Because authentication uses the Contact’s Contact ID, the value in the Contact’s Visibility Control field can be determined.

The Visibility Control field is located on the Event, Event Item, Contact (for Experience Clouds), Attendee, and Session objects. The field’s standard picklist values include Member, Non-Member, VIP, and Press. Customized options can also be added.

Once a value is chosen, dynamic Events/Event Items (Tickets) will be shown to only those Contacts with the matching value. For example, if an Event Item's Visibility Control = "Member", only Contacts with Visibility Control = "Member" will see the Event Item.

Referencing the Contact ID, also auto-populates the Attendee Form with the standard Contact fields.

To read more about Visibility Control, click here.

Iframes in the Community

You can alternatively use iframes to embed an Event's webpage onto your Community instead of using the Community component. This allows you to add customizations that are not currently supported by the Community component.

Even though the iframe is inside the Community, it does not pull in the currently logged-in user as the Events Listing component does, so you will need to set up SSO authentication.

Frequently Asked Questions

Q: Do I need to generate an SSO code for each Contact?
A: Yes, you must generate a unique SSO code for each Contact. No additional custom code is needed when using Salesforce as the identity provider. When using a 3rd party identity provider, you must generate the SSO code using the Context Key Blackthorn provides and each user’s Contact ID.

Q: Do I need to generate an SSO code for each Attendee?
A: No, Attendees can’t use SSO authentication. Attendees need to use the AttendeeLink URL from the Attendee record.

Q: Can I use AWS Key Management Service?
A: No. Different encryption libraries have different preferences for encrypting data. AWS Key Management Service is not compatible with Blackthorn’s solution.

Q: How do we enable authentication for a website?
A: If you are not using a Salesforce-associated method for logging into your website (e.g., Salesforce Authenticator), you must set up a process to pull the Contact ID from Salesforce into your website.

Q: Should the orgID and expiry value be encrypted in addition to the Contact ID?
A: Only the Contact ID must be encrypted. The org ID can be encrypted, but this will make the size of the key significantly longer.

Q: Should the encrypted value be stored and reused, or is generating a new one after each page refresh the correct approach?
A: The SSO key can be reused, and its expiration is based on the TTL used when generating it. However, creating a new key on every page refresh is a good practice.

Q: How do I identify an empty orgid and expiry?
A: Full stops (periods) before and after are required to identify an empty orgId and expiry. For example, if the orgID is blank, you will see something like: .12345.170000000

Q: How do I encrypt/decrypt the Contact ID?
A: Use the example code below to create code to encrypt/decrypt the Contact ID, which will then be used in the data-sso attribute:

import * as crypto from 'crypto';
import { getContextKey } from '../utils/contextKeyGenerator';
import { encode64 } from '../utils/encodeBase64';
import { DecodedContext } from '../types/sso-context';
const encodeContext = (context: DecodedContext, secretKey: Buffer): string => {
  const iv = crypto.randomBytes(16);
  const plaintext = Buffer.from([ context.orgId, context.subjectId, context.expiresAt ].join('.'), 'utf8');
  const cipher = crypto.createCipheriv('aes256', secretKey, iv);
  const encrypted = Buffer.concat([iv,  cipher.update(plaintext), cipher.final() ]);
  return encrypted.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
};

Q: How do I auto-resize the iframe and use SSO authentication?
A: If you want to use auto-resizing on your iframe along with SSO authentication, add a manual listener to the page and parse through the Events coming from the Blackthorn frame. This means the iframe is authenticated with a simple script, and the custom listener catches the Events to resize.

Below is an example script:

<html>
<head>
    <title>BTEmbed</title>
    <script src=https://events.blackthorn.io/embed.js> </script>
    <style>
        body{
            overflow: hidden;
        }
    </style>
</head>
<body>
    <script type="text/javascript" src="https://events.blackthorn.io/loader"
        data-path="/XXXXXXX/g/XXXXXXXXXX"
        data-sso="XXXXXXXXXXXXXXXXXXXXXXXXXXX">
    </script>
    <script type="text/javascript">
        window.addEventListener('message', message => {
            console.log(message);
            console.log(message.data.req.method);
            console.log(message.data.req.params);
            let params = message.data.req.params
            if(message.data.req.method == 'CONTENT_SIZE_CHANGED'){
                let mount = document.getElementsByClassName('bt-eventsapp-container')[0];
                mount.style.height = params.height + 'px';
                mount.getElementsByTagName('iframe')[0].style.height = params.height + 'px';
                parent.postMessage(params.height);
            }
        });
    </script>
</body>
</html>