Single Sign On

SSO

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

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

SSO is available on all plans, including the Free plan.

How it works

After adding your SSO provider, your users will be able to easily join the event using their existing account details without having to manually register.

How to set up SSO

Social Login Providers

Support is included for the following providers:

• Google
• LinkedIn
• Twitter
• Facebook
• Microsoft

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

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

Setting up OAuth2 or SAML2

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"]
    }
}

Key	Result
id	123
names.full_name	Robert Smith
names.first	Robert
names.last	Smith
names.nicknames.0	Rob
names.nicknames.1	Robbie

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.

Always use SSO nicknames

If you have a custom provider (OAuth2, SAML2) enabled, you will see this option.

This option is not available if you have any social login providers turned on.

With this option turned on, registered users will not be able to change their nickname in the chatroom, and the nickname passed via SSO will always be used.

By default, this option is turned off to allow users to quickly change their nickname in the chatroom.

If you prefer that their SSO nickname is always used, you can use this option.

SSO Conflicts

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

This is usually very rare, 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.

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.

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 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 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.

Errors while logging in

Error Code	Description	Resolution
IOU2URL	Invalid Authorize/AccessToken/GetUserInfo URL.	Please check your settings again and make sure you have valid URLs entered for all of those settings.
O1PACE	Error parsing authorization callback.	Your provider returned an invalid response. Please ensure that all settings are correct.
O1RSE	Error getting request secret from request token.	Please ensure all settings are correct -- this may be due to an invalid consumer key or secret.
O1GATE	Error 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, TO2	Error getting user information from identity provider.	Your provider returned an invalid response. Please ensure that all settings are correct.
DEO1, DEO2, DEO3	Error decoding user information from the identity provider.	Your provider returned an invalid response. Please ensure that all settings are correct.
RR1	Error reading response from identity provider.	Your provider returned an invalid response. Please ensure that all settings are correct.
UM1	User 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.
CO1	Error converting authorization code into a token.	Please ensure all settings are correct -- this may be due to an invalid client ID or secret.
SML2GCFE	Error: obtaining SAML2 configuration.	Please ensure all settings are correct -- this may be due to an invalid metadata URL.
SML2RE1	Error retrieving SAML2 assertion information.	Your provider returned an invalid response. Please ensure that all settings are correct.
SML2IT1	Error: 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.
SML2NIA1	Error: Not in audience.	Audience URI is incorrect. Check your SSO settings and provider settings and make sure that audience URI is set appropriately.

Support

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