Qulture.Rocks has an integration with single-sign-on (SSO) providers using the SAML v2.0 protocol. Through this, it is possible to make the login to the Qulture Platform the responsibility of your company's directory system (Identity Provider, or IDP), such as ADFS, Azure AD or Google.
For integration to work, you need someone from your company's IT team, who is familiar with the directory/SSO system you use.
If you are having any problems, be sure to read the FAQ and Common Errors sections below. It helps you to quickly resolve the problems that come up most often.
With this integration, user login is the responsibility of the client and not Qulture.
WARNING: This SSO integration does not have user provisioning, i.e. it does not automatically create accounts on the Qulture Platform. Only registered users will be able to log in. Read about user base integration here.
The following diagram illustrates in simplified form the SSO's flow and User Base Synchronization.
📜 How does the configuration work?
ATTENTION: DO NOT ACTIVATE THE LOGIN REQUIREMENT BY SSO BEFORE TESTING THE LOGIN.
We recommend to make the IT person responsible admin of the company while she is configuring, so she can create users in Qulture without asking anyone.
To set up SSO, just follow the steps below:
1. With admin permission, click Organization > Integrations;
2. In the "Single Sign On" section, click "Enable SAML";
3. Click "Download Metadata";
4. Configure your application on the provider.
⚠️ Important: Make sure that you set the email as the user identifier.
5. Generate the metadata from your provider and upload it to our platform.
6. Perform all the necessary tests, once everything is working as expected click on "Enable mandatory SSO login".
👤 What to do when some employees do not have email?
The most common case in SSO setup is to use email as the user identifier. However, in some companies, there are employees who have no email. In this case, the Platform supports an alternative field configuration called external_uid. An example of use would be to use people's CPF, instead of email to send as external_uid. An important point is that this number must be unique in the company, i.e. each user registered in the Qulture Platform must have a unique identifier. In addition, this field must follow the logic of the CPF, and no other type of document (national or international) can be used instead.
If you need to use another identifier field, follow these steps:
-
Users in Qulture
-
In your user registration method, add the identifier field in the external_uid attribute and make sure that all users have this field filled in.
-
Those who do not have this field will not be able to log in. It is not possible to identify some users with email and others with external_uid.
-
-
-
SSO
-
After step I, before performing the SSO configuration on the Platform, call on the chat and request the activation of the external_uid configuration.
-
Once you receive the confirmation that it is active, follow the configuration steps normally, remembering to send your identifier field.
-
Remember to only activate the requirement after you have done the login test!
-
-
📢 ATTENCION!!
It is essential that the SSO configuration is done correctly, with emphasis on sending the user identifier field being the email or a unique identifier. By SAML protocol, our system "trusts" the identifier sent by the IDP response. If the same identifiers are sent to two different users, it is possible that one of them will access the other's account.
⚠️Common Mistakes
1. User cannot log in
-
Remember that the user with the same identifier must be registered, active and unlocked in the Qulture platform AND authorized to access your side.
-
It is quite common for a user to try to login with an email different from the one registered in Qulture
-
-
Check if your metadata has changed since it was added to the platform. If yes, upload the file again.
-
Check that you are sending the user identifier field correctly (email or other)
-
Make sure the IDP user has the same email or identifier as the user registered in Qulture. It is quite common to receive calls with failed login attempts with different emails between the bases.
2. User authenticates but falls into Qulture login screen
This problem is not very common, but it has happened: the clocks of the provider and our server may be out of sync and the IP return on our server arrives at one time and the condition arrives in the future. An example:
1. Order arrived on "2014-07-17T01:00:00Z".
2. Condition in SAML response:
<saml:Conditions NotBefore="2014-07-17T01:01:18Z" NotOnOrAfter="2014-07-18T06:21:48Z">
It is possible to ask Qulture for a higher tolerance, called drift. Since this tolerance increases security risks, we recommend that the drift be as small as possible, at most 30 seconds and be temporary until the IP clock is synchronized.
🔎 I need help from Qulture to find a problem
If you have made sure it is not one of the common problems described above and a user still cannot log in, follow this procedure:
You can open a query call in our technical queries channel which can be accessed through this link.
(i) a confirmation that you have already checked that it is not one of the common errors above
(ii) the user's email address
(iii) screenshot of the login flow (to make it easier to identify the breakpoint
(iv) SAMLRequest and SAMLResponse:
a. Open the code inspector in the browser;
b. Perform a log in attempt by SSO;
c. In the Network tab of the inspector, look for the SSO request, as in the example below;
d. Copy the SAMLRequest and paste it in a request.txt file (send in the body of the email the date field, found in the request header - e.g. Sun, 22 Nov 2020 15:05:13 GMT, do not send a print screen but the text).
e. Find the item with the answer and copy the SAMLResponse and paste it in a response.txt file.
❓ FAQ
-
Does Qulture have an application in my provider (Azure, Okta) so I don't need to do manual configuration?
Not yet, but the configuration is quite simple 😉
-
Is there support for another protocol besides SAML 2.0?
No.
-
Is it possible to integrate with LDAP?
No, only via the described process.
-
Is it possible to create/activate/inactivate users by SSO?
For now the Platform cannot perform user provisioning actions. It is in our plans, but we have no plans to attack this point yet. The good news is that there are several user base integration options that work very well to work around this problem.
-
Is it possible to manage users via AD groups, or permission roles?
No, we only have sign on integration, not provisioning integration. It is not possible to change user permissions in SSO.
-
Do I need a different configuration for the mobile app?
No, the login flow is the same as for the web.
-
Do I need to create an approval environment to configure it?
No, there is no problem with this configuration occurring parallel to use, since we only force access through SSO after everything has been tested and confirmed.
-
My IT doesn't know very well how to do this, can Qulture configure it for me?
We do not perform the configuration on the client's side; it needs to be done by the responsible area in your company.
-
How will the user log in?
He can access our login screen and click on SSO or go directly to the login screen that you define internally.
-
Will users be created automatically with this integration?
No, our SSO integration does not create new users on the platform, and for that, we have some user base integration options.
-
Is it enough to include a new user in Qulture.Rocks that he will be able to access via SSO automatically?
No. It is necessary to include this new user (email) in the group of people who can access QR via SSO, within the single-sign-on configuration itself.
-
How does the restriction that forces login via SSO work?
When we enable this option, we block a user from changing passwords in Qulture and change all passwords to random values. This means that a user in your company can only log in through SSO. Another consequence of this option is that the links in the emails sent by the Qulture Platform will now go with the link to your SSO login screen.
-
Is it possible to have more than one provider per company?
Currently our platform does not support more than one provider.
-
I activated the SSO login requirement and now I can't login. What should I do?
You can call us on chat explaining the case and asking to remove the SSO login requirement in your company. After the person attending you validates the legitimacy of the request, he will disable this option and you can request a password reset email on the platform.
-
Is it possible to change the URL that leads to my SSO?
By default, when we create a company "My Company", we set the field that determines the URL (called the slug) to "my-company". If you want to change it, disable the SSO login requirement and send an email to the account manager with the new name. You will need to redo the SSO configuration steps.
-
What happens when a user clicks on forgot password on the Qulture login screen?
The Platform sends an email explaining that the company uses Single Sign On login and directing to the login screen of the company's Identity Provider.
Examples
This section provides examples of configuration on Identity Providers.
Microsoft Azure AD
Note: the video has no sound anyway ;)
Okta
If you have any questions, please contact us via chat.