Introduction

This page explains how to connect your identity provider to FinologeeBKO with OpenID Connect. For the overview of SSO, the onboarding sequence and the choice between protocols, see Single Sign-On (SSO).

The generic sections come first: the values to register, the requirements and what to send to Finologee. Examples for specific identity providers follow.

Placeholders

Provider-specific placeholders are explained in the example sections.

---

Values to register in your identity provider

Finologee sends you the connection identifier {alias}. Register FinologeeBKO in your identity provider with the following values.

📘

Sandbox values

The values above are for production. Finologee sends the sandbox values together with the connection identifier.

---

Requirements

Your identity provider must meet the following requirements:

• Email in the ID token: the ID token must contain the email claim, with the user's email address. It must be identical to the email address of the user in FinologeeBKO.
• Discovery document: your identity provider must publish a standard discovery document at {issuer-url}/.well-known/openid-configuration. The Finologee IDP reads your endpoints and signing keys from it, so key rotation on your side needs no action from Finologee.
• Client authentication: the Finologee IDP authenticates to your identity provider with a client secret.

📘

Private key JWT on request

If your policy does not allow client secrets, the Finologee IDP can authenticate with a signed JWT (private key JWT) instead. Ask Finologee for this option: Finologee provides the public certificate to register in your identity provider.

---

What to send to Finologee

Once your identity provider is configured, send Finologee:

• Your {issuer-url}, or the full URL of your discovery document
• The {client-id} of the FinologeeBKO application
• The client secret and its expiry date, through the secure channel Finologee indicates. Never send a client secret by plain email.
• Confirmation that the email claim is included in the ID token
• The label for the login button, for example the name of your organisation

---

Example: Microsoft Entra ID

These steps use the Microsoft Entra admin center. You need at least the Application Administrator or Cloud Application Administrator role.

Placeholders for Microsoft Entra ID

Steps

1. Browse to Entra ID > App registrations and select New registration.
2. Enter a name, for example FinologeeBKO.
3. Under Supported account types, select the single tenant option.
4. Under Redirect URI, select the Web platform and enter the redirect URI from Values to register. Select Register.
5. On the Overview page, note the Application (client) ID and the Directory (tenant) ID. You can also select Endpoints and copy the OpenID Connect metadata document URL.
6. Open Certificates & secrets > Client secrets and select New client secret. Choose an expiry period, then copy the Value immediately: it is only shown once. Note the expiry date.
7. Open Token configuration, select Add optional claim, choose the ID token type and add email, given_name and family_name. If you are asked to turn on the Microsoft Graph email and profile permissions, accept.
8. Open API permissions and check that the Microsoft Graph delegated permissions openid, email and profile are present. Add any that are missing, then select Grant admin consent.
9. Optional, to restrict access: browse to Entra ID > Enterprise apps, open the FinologeeBKO application, set Assignment required? to Yes under Properties, then add the users or groups who may sign in under Users and groups.

Values to send

🚧

Email claim in Microsoft Entra ID

Microsoft Entra ID only includes the email claim when the user's Email (mail) attribute is populated. A missing email address is the most common cause of a failed first login. Check the attribute on each user before testing.

Microsoft Entra ID error codes

See Microsoft's error code reference and optional claims reference.

---

Example: Okta

These steps use the Okta Admin Console.

Placeholders for Okta

Steps

1. Go to Applications > Applications and select Create App Integration.
2. Select OIDC - OpenID Connect as the sign-in method and Web Application as the application type.
3. Enter a name, for example FinologeeBKO.
4. Under Grant type, keep Authorization Code selected.
5. Under Sign-in redirect URIs, enter the redirect URI from Values to register. Leave Sign-out redirect URIs empty.
6. Under Assignments, choose who may sign in, for example a group, then save.
7. On the General tab, note the Client ID and the Client secret.

Values to send

See Okta's documentation on creating an OIDC app integration and on authorization servers.

---

Example: Keycloak

This example applies when your own organisation runs Keycloak as its identity provider.

Placeholders for Keycloak

Steps

1. In the admin console, select {realm}, open Clients and select Create client.
2. Set Client type to OpenID Connect and enter a Client ID, for example finologeebko.
3. Turn Client authentication on and keep Standard flow enabled.
4. Under Valid redirect URIs, enter the redirect URI from Values to register, then save.
5. Open the Credentials tab and copy the Client secret.
6. Check that the profile and email client scopes are assigned to the client, so that email, given_name and family_name are in the ID token. They are assigned by default.

Values to send

See the Keycloak Server Administration Guide, section "Creating an OpenID Connect client".

---

Client secret rotation

The client secret belongs to your identity provider, and you decide its expiry date. When the secret expires, SSO stops working for every user of the connection.

1. Before the secret expires, create a new secret in your identity provider. Keep the old secret active.
2. Send the new secret and its expiry date to Finologee through the secure channel.
3. Wait for Finologee to confirm that the connection uses the new secret.
4. Delete the old secret.

Plan the renewal a few weeks before the expiry date, and record the date in your own calendar.

---

Troubleshooting

If the problem remains, contact [email protected] with the time of the attempt, the user's email address and any error code shown.

---

Related documentation

• Single Sign-On (SSO) - Overview, onboarding sequence and choice of protocol
• SSO with SAML 2.0 - The same setup with SAML 2.0
• User & Groups - Enabling SSO for each user