SSO (OIDC)

Login through an external identity provider, instead of a password managed by Q247. Every provider compliant with OpenID Connect 1.0 is supported, including Microsoft Entra ID, Okta, Google and Keycloak.

This integration is responsible only for login. Creating and synchronizing accounts is handled separately by SCIM Provisioning, and the two can be deployed independently.

Two authentication modes

The organization chooses one mode for all of its users at once:

Mode	What login looks like
Password + MFA	a password managed by Q247, with a second factor from an authenticator app
SSO (OIDC)	redirect to the identity provider, with no password on the Q247 side

Choosing SSO reveals the integration fields. The login screen itself in both modes, from the user's perspective, is described in Log in.

Changing the mode signs out the whole organization

Switching between password and SSO invalidates current sessions. All users have to log in again, now with the new method. It is worth planning this outside working hours and giving teams a heads-up.

How it works, in brief

Q247 fetches a document describing the provider's endpoints from the Discovery URL, redirects the user to log in and receives back a code, which it exchanges for a token. From the token it reads the e-mail address and uses it to find the account in the organization.

The practical consequences of this flow, which network and security teams ask about:

• All of Q247's communication with the provider is outbound from Q247. The identity provider never connects to Q247's servers, so enabling SSO does not require opening inbound traffic.
• The Discovery URL address must point to a public IP address. An identity provider available only on the internal network will not work.
• Q247 requests only the openid, email and profile scopes, so it does not gain access to the rest of the data in the identity directory.

The full specification, including the algorithms, client secret protection and the traffic direction table, is in SSO Security.

Prerequisites

• An application registered with the identity provider, which provides the identifier and secret.
• The provider's Discovery URL address, publicly available.
• User accounts that already exist in Q247, created manually or through SCIM. SSO does not create accounts.
• The administrator role in Q247, because the Configuration section is available only to administrators.

Fields to fill in Q247

Field	What it does	Example
Callback URL	the return address, fixed and generated by Q247. Copy it and paste it into the identity provider	https://app.q247.io/api/auth/idp/oidc/callback
Discovery URL	the address of the OIDC metadata document. Must contain the .well-known/openid-configuration segment	https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
Client ID	the identifier of the application registered with the provider	a1b2c3d4-e5f6-...
Client Secret	that application's secret. Given once, stored only in encrypted form	~Abc123...

The Discovery URL address depends on the provider and follows a fixed pattern:

Provider	Discovery URL address
Microsoft Entra ID	https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
Okta	https://{your-domain}.okta.com/.well-known/openid-configuration
Google	https://accounts.google.com/.well-known/openid-configuration
Keycloak	https://{host}/realms/{realm}/.well-known/openid-configuration

Configuration on the identity provider side

In the application registered with the provider, set:

• Redirect URI, also called Callback URL: the value copied from Q247, in the form https://{platform-domain}/api/auth/idp/oidc/callback.
• Flow type: Authorization Code Flow.
• Scopes: openid, email, profile.
• ID Token: must contain the email claim. This is how Q247 recognizes which account the person logging in belongs to.

The detailed paths for registering an application differ between providers and change independently of us, so for these we refer to the chosen provider's own documentation.

A missing e-mail claim stops login without a clear reason

If the ID token does not contain an e-mail address, authentication at the provider goes through correctly, but Q247 has nothing to map the identity to an account with. The symptom then looks like a problem on the Q247 side, while the cause lies in the claim configuration at the provider.

Requirements for the user account

For a given person to be able to log in through SSO, their account in Q247 must meet three conditions at the same time:

1. Exist, created manually in Users and Teams or synchronized through SCIM.
2. Have active status with access. A blocked account or one marked as active without access will not pass login.
3. Have an e-mail address matching the one the provider returns in the email claim. A difference even just in the domain means no match.

The third condition is the most common cause of failed logins after deployment, especially in organizations that have migrated their mail domain or have alternate addresses in the directory.

Verification

After saving the configuration, check in this order:

1. The configuration save went through, that is the Discovery URL address was not rejected. Rejection means the address is missing a required segment or is not publicly reachable.
2. Login on a test account, preferably an account other than your own, so as not to lock yourself out with a faulty configuration.
3. E-mail address match for several accounts from different teams, if the organization has more than one mail domain.

See also

• SSO Security: the flow, algorithms, traffic direction
• SCIM Provisioning: creating and synchronizing accounts, independent of login
• Log in: the login screen from the user's perspective
• Permissions: what an account can see after logging in