Single Sign On (SSO) enables your users to auto-login on Arena.im when they're already logged into your online portal. Your system will need to let Arena.im know which user is currently logged into your site, in a secure manner.
To accomplish this, our widgets provides a set of basic methods and handlers, outlined below:
Notes:
SSO implementation only works when widgets are embedded using JavaScript. It won't work for iFrame embeds.
This feature is available only for Enterprise plans, please contact your Account Manager so they can enable it for you.
Step 1: Wait for the SSO to be ready
You must wait for the Arena SSO to be ready using the listener below. After the API is ready, it will call the startArenaSSO function.
if (window.arenaSSO) {
startArenaSSO();
} else {
document.addEventListener(
'arena-im-api-ready',
startArenaSSO,
false
);
}Step 2: Initialize the SSO
To initialize the Arena SSO, you have to define the startArenaSSO function and within that function, a call to window.arenaSSO.initialize method. In the initialize function you have to call your sign in and sign out respective functions. Also, you can provide the logged user information by calling the Arena SSO authenticate method, as in the example below:
New: In customProps it is possible to add the desired custom value considering the key/value. Initially designed for the Location field.
function startArenaSSO() {
window.arenaSSO.initialize({
// Called when the user clicks on sign in in an Arena Widget
signIn: () => { /* call your sign in function */ },
// Called when the user clicks on sign out in an Arena Widget
signOut: () => { /* call your sign out function */ },
});
// Provide the logged user to Arena SSO
window.arenaSSO.authenticate({
id: "2345",
email: "[email protected]",
picture: "https://randomuser.me/api/portraits/women/12.jpg",
name: "Kristin Mckinney",
customProps: [{
label: 'city',
value: 'Paris',
},
{
label: 'country',
value: 'France',
}],
});
}
Step 3: Call Authenticate and Sign out Methods
On your website, when you finish authenticating the user, you have to inform the user's information to the Arena SSO. Check the example below:
// Provide the logged user to Arena SSO
window.arenaSSO.authenticate({
id: "2345",
email: "[email protected]",
picture: "https://randomuser.me/api/portraits/women/12.jpg",
name: "Kristin Mckinney"
});
Arena SSO will create the user profile if it's the first time or just return their information if it's not the first time.
And when your user sign out, you have to call the Arena SSO method signOut, as in the example bellow.
// Sign out the user on Arena SSO
window.arenaSSO.signOut();
SSO FAQ
Q: Which fields are required when authenticating a user?
A: You must provide at least `id`, `email` and `name`. The id does not require any special format, and we usually recommend it is set with the same value as the application where Arena widgets are being embedded into.
Q: I’m getting `Error: Illegal argument` after the page loads
A: Please double-check if you are setting all required fields, as well as initializing the SSO feature exactly as described on this page.
Q: `Cannot read properties of undefined (reading …)` is being shown at the browser console
A: Make sure you’ve followed all steps from this page. Also, you can ask your Account Manager if SSO is already enabled for your account.
Q: I’ve followed all instructions and it did not work :(
A: Another important setting is to enable SSO login on the Arena dashboard for the widget you’re embedding.
Get in touch with Arena’s Customer Support so we can help you with any other technical issues you’re facing.