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

Social Login Providers

Support is included for the following providers:

  • Google
  • LinkedIn
  • Twitter
  • Facebook

All providers are enabled by default, but you can configure which providers are enabled in organization settings.

Please note that you cannot use zero click SSO alongside social login providers.

If you'd like to use the WordPress Plugin with social login providers enabled, you can use advanced settings while syncing (see the instructions below).

You can read more about social login providers here, including details on how to use custom credentials.

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 hit the save changes button below.

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.

Now that SSO is enabled, you just need to sync your WordPress plugin settings with your Organization.

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

WordPress SSO Sync first step

Here, you'll need to enter your organization URL.

Your organization URL will either look like https://organizations.minnit.chat/123456 or https://yourname.minnit.org if you've set up a vanity subdomain.

Once entered, click on the Proceed button below.

WordPress SSO Sync second step

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.

WordPress SSO Sync final step

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.

If you aren't using the gutenberg editor, you won't be able to use the block element.

You can use this embed code instead:

<minnit-chat data-chatname="add your chatroom link here" class="wp-block-minnit-chat-chat-embed"></minnit-chat>

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
rankmoderatorSpecify the user's rank for this chat. Possible values are: visitor, regular, moderator, manager, ownerOptional
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", "rank": "moderator", "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 as an environment variable, 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.

Custom Return URL

Note: If you are using Zero-Click SSO, this does not apply to you.

When you login via SSO using any other method, we rely on a pop-up or new tab to relay information back to the chat.

In certain circumstances, browsers may not have support for pop-ups or new tabs (e.g. links opened in Facebook Messenger or Telegram), which will take the user away from the chat when logging in via SSO.

In your organization settings, you can set the default custom return URL to ensure that users return to the page where the chat is embedded after successfully logging in.

For example, if your chat is embedded on https://example.com/chat, you would set this URL in your organization settings.

You may have your chat embedded on several different pages, in which case you may want to override the default.

You can set a specific custom return URL inside of the embed URL of the chat by adding &cssoreturn=your_url_here like this:

<iframe src="https://example.minnit.org/Main?embed&cssoreturn=https://example.com/chat" style="border:none;width:90%;height:500px;" allowTransparency="true"></iframe>

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.

Zero-Click SSO

Testing with the WordPress plugin

If you're logged into the owner account for your organization, Zero-Click SSO will be ignored and you'll stay logged into your existing account.

You may see a message like this:

Zero Click ignored message example

We suggest using an incognito/private window, or a separate browser to test Zero-Click SSO if you're logged into the owner account.

Testing with the WordPress plugin using Advanced Settings

If you're logged into an account already, you won't see the SSO option to login.

We suggest using an incognito/private window, or a separate browser to test SSO using Advanced Settings if you're logged into the owner account.

Testing a manual integration

You can enter an encrypted ssotoken into organization settings and retrieve the decrypted output, so you can be sure that encryption is working correctly.

OAuth2/SAML2

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.

Troubleshooting

WordPress Plugin Errors

Error CodeDescriptionResolution
invalid_redirect_uriThis means the Authorized Redirect URI in the WordPress plugin settings does not match the Authorized Redirect URI in your organization's SSO Settings.We recommend resyncing the WordPress plugin settings to solve this issue.
invalid_clientThis means the client ID or secret in the WordPress plugin settings does not match the client ID or secret in your organization's SSO settings.We recommend resyncing the WordPress plugin settings to solve this issue.

Most errors can be resolved by syncing your WordPress plugin settings with your organization again.

Errors while logging in

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.