Set up single sign-on

Konekti supports single sign-on (SSO) using SAML 2.0. Setting it up is an exchange of details in two directions: you tell your identity provider about Konekti, and you tell Konekti about your identity provider.

Two ways to set this up

You can configure single sign-on in two places, and it is worth choosing before you start:

• In the product, on the Organization settings page. This is the simpler route and the steps below walk through it. It needs a super admin who can already sign in, so it suits a Konekti that is already up and running.
• In your deployment configuration. Choose this when you want single sign-on from the very first sign-in, when nobody has an account yet, or when your policy says configuration belongs with the deployment. See Setting it up in your deployment.

Settings in your deployment take precedence. When single sign-on is configured there, the Organization settings page shows the values as read-only.

The steps below cover the in-product route, which needs SAML 2.0 to be one of your allowed authentication methods.

Before you start

You need:

• An identity provider that supports SAML 2.0, such as Microsoft Entra ID, Okta, Google Workspace, or ADFS.
• Permission to register a new application in it.
• An identity provider that sends the user's email address. Konekti matches people on their email address.

tip

Do the configuration from a username and password super admin account, and keep that account. While both sign-in methods are allowed, it is how you get back in if something is wrong with your SSO settings.

It stops being a way back in once you turn username and password off, because password sign-in is then refused for everyone. See If you get locked out.

Step 1: Give your identity provider Konekti's details

Konekti works out the values your identity provider needs from a single setting.

1. Open Organization settings and find SAML settings.
2. Fill in Konekti URL. This is the address people use to reach Konekti.
3. Konekti fills in the four values below it. Copy each one into your identity provider with the copy button next to it.

Konekti value	What your identity provider usually calls it
Konekti Entity Id	Entity ID, or Audience
Konekti Reply URL	ACS URL, or Assertion Consumer Service URL. Use the HTTP-POST binding
Konekti Login URL	Sign-on or login URL
Konekti Logout URL	Sign-out or logout URL

note

If Konekti runs behind a reverse proxy or load balancer, set Konekti URL to the public address people actually use. Otherwise Konekti uses the address it sees itself, which may be an internal hostname, and the values will not match what you registered.

Step 2: Check the email address claim

Your identity provider has to include the person's email address. Konekti looks for it in these claims and uses the first one it finds:

1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
2. urn:oid:0.9.2342.19200300.100.1.3
3. email
4. http://schemas.xmlsoap.org/claims/EmailAddress
5. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
6. The NameID, as a fallback

Most identity providers already send one of these, so there is often nothing to do. See Notes for your identity provider. If none of them is present, sign-in fails with ERR113.

Step 3: Tell Konekti about your identity provider

Under Configuration method, choose how Konekti gets your identity provider's details.

Metadata endpoint

Fill in Identity Provider metadata URL and Konekti reads everything else from your identity provider, including the signing certificate.

This is the easier option to keep running, because certificate changes are picked up automatically. Konekti needs to be able to reach that URL over HTTPS.

Manual values

Use this when Konekti cannot reach your identity provider's metadata URL. Fill in:

• Identity Provider Entity ID
• Identity Provider Certificate. Paste it, or use the upload button to load a .cer, .pem, or .crt file.
• Identity Provider Login URL
• Identity Provider Logout URL, optional. See Signing out.

With manual values you have to replace the certificate yourself whenever your identity provider rotates it. If you do not, sign-in stops working.

warning

Switching between Manual values and Metadata endpoint clears the fields belonging to the other option. Copy anything you still need before you switch.

Step 4: Test the sign-in

Save your changes, then open the Konekti sign-in page and sign in. You are sent to your identity provider, and once you have authenticated there you come back to Konekti already signed in.

Test with an account other than your fallback admin account, so you know an ordinary user can get in too.

Leave Username + password switched on until you have seen single sign-on work for real people. Turning it off is the last step of a rollout, not the first. See Authentication for what changes when you do.

note

Sign-in has to start from Konekti. Opening Konekti from a tile or shortcut in your identity provider's own dashboard does not work, and fails with ERR112.

Signing out

You can have signing out of Konekti sign the person out of your identity provider as well:

• With Metadata endpoint, Konekti picks the logout address up from the metadata.
• With Manual values, fill in Identity Provider Logout URL.

Without a logout address, signing out of Konekti only ends the Konekti session. The person can sign straight back in without entering credentials, because they are still signed in at the identity provider.

Signing out at your identity provider does not end an existing Konekti session by itself.

Setting it up in your deployment

Everything on this page can also be set outside the product, in your deployment configuration. Konekti picks it up from environment variables.

Two things to know:

• Deployment settings take precedence. What you set there is what Konekti uses, and the Organization settings page becomes read-only. That holds even if someone had already configured single sign-on in the product.
• If you would rather manage sign-in inside the product, leave the authentication method out of your deployment configuration altogether.

These are the two settings that control how people sign in:

Setting	Values
Authentication__AllowedAuthenticationMethods	1 username and password, 2 single sign-on, 3 both
Authentication__UserProvisioning	0 accounts have to exist already, 1 accounts are created on first sign-in

The identity provider details from step 3 have matching settings under Authentication__Saml__, and your deployment documentation has the full list.

Starting with no users yet

This is how you set up single sign-on on a brand new Konekti, where nobody has an account yet and so nobody can open Organization settings.

Configure single sign-on in your deployment configuration, then have the first person sign in through your identity provider. Because there are no accounts yet, that first sign-in creates their account and makes them a super admin. They can then add everyone else in the product as usual.

You do not have to switch on automatic account creation for this. The first sign-in works either way. That setting only decides what happens for everyone who signs in after them.

If sign-in fails

Code	What it means
ERR111	Konekti could not validate the response. Check the certificate and the server clock.
ERR112	The response could not be read. This is also what you get if sign-in started at the identity provider instead of at Konekti.
ERR113	The response contained no email address. Check your claim mapping in step 2.

Two things catch people out most often:

• Clock drift. Sign-in responses are only valid for a short window, and Konekti allows two minutes of difference. If the Konekti server's clock is off, sign-ins fail with ERR111.
• Values that do not match. The entity ID and reply URL you registered with your identity provider have to match what Konekti shows exactly, including https and any trailing path.

If you get locked out

When your organization only allows single sign-on, there is no password to fall back on. If your identity provider becomes unreachable, a certificate expires, or a setting turns out to be wrong, nobody can sign in, including super admins.

Getting back in means changing the allowed sign-in methods from outside the sign-in flow, which needs whoever runs your Konekti installation.

tip

This is far easier to prepare for than to solve under pressure. Before you turn username and password off, make sure single sign-on has worked for real users, and make sure you know who to reach if it stops working.

Notes for your identity provider

Microsoft Entra ID

Create an Enterprise Application using SAML. Entra sends the user principal name in the name claim, which for most tenants is the person's email address, so there is usually no extra mapping to do. The metadata URL looks like https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml.