Skip to main content

Single Sign On

SSO

Single Sign On (SSO) is a powerful feature that allows you to connect an existing account database to Minnit.

This vastly speeds up registrations and allows users to join the chat with their existing account data including their username, nickname, profile picture with just a few clicks.

SSO is available on the Basic plan and higher.

How it works

After adding your SSO provider, your users will be able to easily join the chat using their existing account details without having to manually fill in all of their account details.

Zero-Click SSO Demo

Zero-Click SSO Demo using the Minnit Chat WordPress plugin

OAuth2/SAML2 SSO Demo

OAuth2 SSO Demo using the Minnit Chat WordPress plugin

How to set up SSO

WordPress plugin

If you haven't already installed our plugin, please install it here.

Once installed, go to the WordPress plugin settings and enable Single Sign On (SSO) and save changes.

If you want to require users to click a button in the chat to login, check the box for Advanced Settings and hit save changes. We don't recommend this for most integrations.

Click on "Sync SSO Settings to your Organization" and enter your organization URL, and click on Sync Now to continue.

This will redirect you to the organization SSO settings page, where you'll see a list of any of your existing providers, or a new provider would be created for you if you didn't have any existing providers.

If you checked the box for Advanced Settings in the plugin, you'll want to set the login button text, register button text and/or images here and check the box for "Require users to sign in via SSO before they can chat?" so users will be prompted to login as soon as the chat loads.

You can always change these settings later.

Click on "Import WordPress SSO Data" below the provider that you'd like to apply the settings to.

Next, it will return you back to the WordPress Minnit Chat plugin settings page, confirming that the settings have been saved.

Once this is done, you can add your chat to any post or page using the block element, and/or use the the site-wide chat icon in the plugin settings.

When any of your users loads the chat, they'll automatically be logged in using their existing account details.

However, if you enabled Advanced Settings, users will see a button to log into the chat once the chat loads.

Short video showing the setup process

Setting up Zero-Click SSO manually

Zero-Click SSO is easiest way to log your users in automatically when they join the chat, without them having to press any buttons.

This feature requires you to have some developer experience.

With just a few lines of server side code, you'll be able to securely embed the user's data directly into the URL.

To get started, you'll need make changes to your organization's SSO settings to enable Zero-Click SSO.

To access the organization SSO settings page, go to your organization's homepage and click on Organization Settings in the navigation bar and click on SSO.

Once there, change the type for one of your providers to Zero-Click, check the box by Active to turn it on, and save changes.

You'll see an encryption key here, which will be used to encrypt user data using AES-256-GCM in the chat iframe URL.

The unencrypted ssotoken is simple JSON, containing the following:

KeyExampleExplanationRequired
userid1Unique identifier for user. Doesn't have to be a number.Yes
usernameRobertUnique username for user, helpful for @ mentions in the chat.Yes
nicknameRobert SmithNickname for user which doesn't have to be unique. The user can also change this at any time. If left out, it will default to the same as the username.Optional
profile_picture_urlhttps://minnit.chat/images/hotlink-ok/fav64.pngPublicly accessible URL for the user's profile picture, which will be displayed in the chat when they send messages.Optional
max_valid_ts1766987552UNIX timestamp in seconds at which the ssotoken should be considered invalid. If left out, the SSO token is always considered to be valid. We recommend 1 hour of validity.Optional

Using the above examples, the JSON would look like this unencrypted:

{"userid": 1, "username": "Robert", "nickname": "Robert Smith", "profile_picture_url": "https://minnit.chat/images/hotlink-ok/fav64.png", "max_valid_ts": 1640653895}

We've provided code snippets in the most popular languages so you can get started.

<?php
function encrypt($key, $textToEncrypt) {
$tag_length = 16;
$iv_len = 12;
$iv = openssl_random_pseudo_bytes($iv_len);
$tag = ""; //will be filled by openssl_encrypt
$ciphertext = openssl_encrypt($textToEncrypt, "aes-256-gcm", $key, OPENSSL_RAW_DATA, $iv, $tag, "", $tag_length);
return base64_encode($iv . $ciphertext . $tag);
}

$encryptionKey = 'z8pkH$jjNEWEEEe*DwThe4K2iDtjDwYQ'; //your encryption key can be obtained from organization settings

$encryptedSSOToken = encrypt($encryptionKey, json_encode(array("userid" => "1", "username" => "Minnit", "nickname" => "Minnit Chat", "profile_picture_url" => "https://minnit.chat/images/hotlink-ok/fav64.png", "max_valid_ts" => time() + 3600)));

$embedHTML = '<iframe src="https://example.minnit.org/Main?embed&ssotoken=' . $encryptedSSOToken . '" style="border:none;width:90%;height:500px;" allowTransparency="true"></iframe>'; //your embed code can be obtained from the embed chat page

echo htmlspecialchars($embedHTML);

Note: You'll need to modify the code for your integration to do the following:

  1. Add your encryption key from the SSO section of the organization settings page
  2. Get user data from your database when generating the JSON for the ssotoken
  3. Add your embed code from the embed chat page, and add &ssotoken=encrypted_sso_token_here to the URL
  4. Use the embed code in your HTML. The code above simply prints out the embed code either to the console (if applicable) or to the page as plain text.

The encryption key must be kept secret and not displayed to users, as this could be used to log into any account.

We also strongly recommend storing your encryption key in environment variables, or using a secrets storage solution such as AWS Parameter Store to store it.

If your language isn't listed here, please contact support and we'll see if we can help.

Is this secure?

Absolutely!

The encryption type used is AES-256-GCM and it would take trillions of years of non-stop attempts to be bruteforce your encryption key.

You can read more about the security of AES-256-GCM here.

Why should I use this over a typical OAuth2 or SAML2 SSO integration?

Typical SSL integrations requires users to click a button in the chat to login for the first time.

This then redirects them back to your website's login page where they can enter details to login, and then their user data is securely transmitted back to us and we log them into the chat.

By using Zero-Click SSO, user details can be securely embedded into the chat URL and sent when the user connects, creating instant logins upon joining the chat, without the use of any redirects.

We'd recommend using this as it's very easy to implement, but either setup works well and is virtually unnoticeable to the end user.

What happens if the ssotoken is no longer valid due to the timestamp sent in max_valid_ts expiring?

Whenever the ssotoken is used, cookies are set on the user's device that are used on subsequent logins.

If there's no cookies stored, the user will be signed into the chat as a guest (unregistered user).

Note: Cookies may be blocked in certain cases either due to browser settings or third party cookie restrictions.

Setting up OAuth2 or SAML2 manually

If you aren't using our WordPress plugin or Zero-Click SSO, the setup can be more complex.

You or your developer will need to set up either an OAuth2 or SAML2 integration on your website if you don't have one already.

To get started, you'll need make changes to your organization's SSO settings.

To access the organization SSO settings page, go to your organization's homepage and click on Organization Settings in the navigation bar and click on SSO.

Once on the SSO settings page, you can now add your provider and select OAuth2 or SAML2 and fill in the required details.

Unique username key, username key, nickname key etc

Regardless of provider type (OAuth2, SAML2), you'll be required to fill in the unique user key. This is how we'll recognize each user when they try logging in again.

This primary key must be unique for each user, or else users risk gaining access to each other's accounts.

We recommend filling in the other keys (username, nickname, email) as well so you can pull more of your user's information to make the registration process much smoother.

You can test your SSO integration to see the response from your provider if you're not sure what key names to use -- the key names will differ depending on your provider.

Targeting nested JSON and array values

Sometimes your identity provider will return complex JSON, which means you won't be able to use a simple key value to pull the correct value.

If you're using OAuth2, you can target nested JSON and values from arrays.

For nested JSON, separate keys by .

{"info": {"username": "John"}}

info.username would grab the value of John in this example.

For arrays, separate the key by . followed by the number of the value you want to grab.

Arrays always start at 0.

{"names": ["Robert", ["Rob"]}

info.0 would grab the value of Robert, and info.1 would grab the value of Rob in this example.

Here are some detailed examples:

{
"id": 123,
"names": {
"full_name": "Robert Smith",
"first": "Robert",
"last": "Smith",
"nicknames": ["Rob", "Robbie"]
}
}
KeyResult
id123
names.full_nameRobert Smith
names.firstRobert
names.lastSmith
names.nicknames.0Rob
names.nicknames.1Robbie

Note: The JSON your provider returns will be in a different format and the keys will likely be different.

The examples above are used as an illustration to explain how you can target different types of information from the JSON your identity provider returns.

SSO Conflicts

When using SSO, it's possible that there may be a conflict in our database for your users.

This is usually very unlikely, and is almost impossible if you don't allow users to change their usernames.

For example, if someone with the username John logs into your organization, those details will be stored.

If John changes his username on your database, and then someone else uses the username John and then logs into your organization, that will result in a username conflict as the username John is already taken.

While email conflicts can also occur, they are much more rare.

Additionally, passing emails is completely optional if you'd like to avoid any chance of email conflicts.

Automatically resolve all conflicts

If there's a conflict, the user's details who is currently trying to log in will be used.

The conflicting account's details will be amended -- their username will be set to a random username and their email will be removed.

Upon logging in again, the conflicting account's details will be updated to reflect their actual username stored on your database.

This is always turned on if you are using Zero-Click SSO.

Allow users to change their name if there is a conflict

If you allow users to have the same name or you prefer to allow them to set a custom chat username, we recommend enabling this option.

Allow users to change their email if there is a conflict

If you allow users to have the same email or you prefer to allow them to set a custom email, we recommend enabling this option.

Testing your integration

You can use the Test Integration button to test your SSO configuration at any time.

This will return debug information that should help you get the SSO integration working exactly the way you prefer.

For Zero-Click SSO, you can enter an encrypted ssotoken and retrieve the decrypted output, so you can be sure that encryption is working correctly.

For OAuth2/SAML2 SSO integrations, you may not be sure what data your provider returns -- this page will contain the response from your SSO provider so you can select the right unique user key, username key, nickname key etc.

IP addresses

As part of the OAuth2/SAML2 Single Sign On process, we'll need to make requests to your server to retrieve user data.

We never make any requests to your server if you use the Zero-Click SSO process.

We use Cloudflare Workers to make these requests where applicable.

The IP address ranges that Cloudflare uses can be found here.

As part of the request, the header cf-worker will always be set to minnit.chat so you can use this to easily identify requests coming from us.

Please ensure that these IP addresses are whitelisted if you have a server firewall, otherwise SSO requests may fail.

Error glossary

If you're having trouble with your SSO integration, the following error list should help you fix the issue.

Error CodeDescriptionResolution
IOU2URLInvalid Authorize/AccessToken/GetUserInfo URL.Please check your settings again and make sure you have valid URLs entered for all of those settings.
O1PACEError parsing authorization callback.Your provider returned an invalid response. Please ensure that all settings are correct.
O1RSEError getting request secret from request token.Please ensure all settings are correct -- this may be due to an invalid consumer key or secret.
O1GATEError getting access token from request token and secret.Please ensure all settings are correct -- this may be due to an invalid consumer key or secret.
TO1, TO2Error getting user information from identity provider.Your provider returned an invalid response. Please ensure that all settings are correct.
DEO1, DEO2, DEO3Error decoding user information from the identity provider.Your provider returned an invalid response. Please ensure that all settings are correct.
RR1Error reading response from identity provider.Your provider returned an invalid response. Please ensure that all settings are correct.
UM1User ID returned by identity provider is empty.Your provider returned an empty unique user value. Please ensure that your unique user key is set correctly and your provider is returning a unique value for each user.
CO1Error converting authorization code into a token.Please ensure all settings are correct -- this may be due to an invalid client ID or secret.
SML2GCFEError: obtaining SAML2 configuration.Please ensure all settings are correct -- this may be due to an invalid metadata URL.
SML2RE1Error retrieving SAML2 assertion information.Your provider returned an invalid response. Please ensure that all settings are correct.
SML2IT1Error: Invalid time. This is likely because your server time has drifted.Your provider's server's time has drifted. Please check and make sure that the time is correct.
SML2NIA1Error: Not in audience.Audience URI is incorrect. Check your SSO settings and provider settings and make sure that audience URI is set appropriately.
CLMUSSOError: Cannot login manually using Zero-Click SSO.Accounts can't be logged into manually with Zero-Click SSO. Zero-Click SSO only works with the ssotoken present in the URL.

Support

If you're having issues with your SSO integration and you're unable to resolve it, please contact us here.