Introduction

This page explains how to connect your identity provider to FinologeeBKO with SAML 2.0. 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.

If your identity provider can import service provider metadata, you can use the metadata URL instead of entering the values by hand, once Finologee confirms the connection is set up.

🚧

One entity ID for all connections

The service provider entity ID is the same for every FinologeeBKO connection in an environment. Some identity providers, including Microsoft Entra ID, do not allow two applications with the same identifier in one tenant. If your identity provider already has an application with this entity ID, for example for another FinologeeBKO tenant, contact Finologee before you create a new one.

📘

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:

• Signed responses: the SAML response, the assertion, or both must be signed with your identity provider's signing certificate.
• Email address: the NameID, or an attribute, must carry the user's email address. It must be identical to the email address of the user in FinologeeBKO.
• Metadata by URL: your identity provider should publish its SAML metadata at a URL, so that the Finologee IDP reads your endpoints and signing certificate from it. If only a metadata XML file is available, send the file instead.

---

What to send to Finologee

Once your identity provider is configured, send Finologee:

• Your {idp-metadata-url}, or the metadata XML file
• Which attribute carries the email address: the NameID or the name of an attribute
• The names of the attributes that carry the first name and last name
• 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 > Enterprise apps and select New application.

2. Select Create your own application, enter a name, for example FinologeeBKO, and choose the option to integrate an application that is not in the gallery. Select Create.

3. In the application, open Single sign-on and select SAML.

4. In Basic SAML Configuration, select Edit and enter the values from Values to register:

   • Identifier (Entity ID): the service provider entity ID
   • Reply URL (Assertion Consumer Service URL): the Assertion Consumer Service URL
   • Logout Url (Optional): the single logout URL, if you want it

   Alternatively, select Upload metadata file and upload the service provider metadata once Finologee has set up the connection.

5. In Attributes & Claims, select Edit and set:

   • Unique User Identifier (Name ID): source attribute user.mail, name identifier format Email address
   • emailaddress: user.mail
   • givenname: user.givenname
   • surname: user.surname

6. In SAML Certificates, copy the value of App Federation Metadata Url. This is your {idp-metadata-url}.

7. Open Users and groups and assign the users or groups who may sign in.

Values to send

🚧

Email address in Microsoft Entra ID

The user.mail attribute is only filled 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 the guide to SAML single sign-on for enterprise applications.

---

Example: Okta

These steps use the Okta Admin Console.

Steps

1. Go to Applications > Applications and select Create App Integration.
2. Select SAML 2.0 as the sign-in method.
3. Enter a name, for example FinologeeBKO, and continue to the SAML settings.
4. Set Single sign-on URL to the Assertion Consumer Service URL from Values to register.
5. Set Audience URI (SP Entity ID) to the service provider entity ID.
6. Set Name ID format to EmailAddress and Application username format to Email.
7. Under Attribute Statements, add:
   • email: user.email
   • firstName: user.firstName
   • lastName: user.lastName
8. Finish the wizard.
9. On the Sign On tab, copy the Metadata URL. This is your {idp-metadata-url}.
10. On the Assignments tab, assign the users or groups who may sign in.

Values to send

See Okta's documentation on creating a SAML app integration and the SAML field reference.

---

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 SAML and set Client ID to the service provider entity ID from Values to register.
3. Set Valid redirect URIs and Master SAML Processing URL to the Assertion Consumer Service URL, then save.
4. Set Name ID format to email.
5. Make sure assertions are signed: turn Sign assertions on.
6. Add mappers for the email address, first name and last name, for example email, firstName and lastName from the user properties.
7. On the Keys tab, turn Client signature required off, unless you created the client by importing the service provider metadata.

Values to send

See the Keycloak Server Administration Guide, section "Creating a SAML client".

---

Certificate rotation

Your identity provider signs SAML responses with a certificate that expires. When it expires, or when a new certificate becomes active without Finologee knowing, SSO stops working for every user of the connection.

1. Before the certificate expires, add a new signing certificate in your identity provider. Do not activate it yet.
2. Notify Finologee and agree a date for the switch.
3. Finologee updates the connection with the new certificate.
4. Activate the new certificate on the agreed date and test a login.
5. Remove the old certificate once the new one works.

Microsoft Entra ID creates signing certificates with a default validity of three years and sends expiry notices 60, 30 and 7 days before the expiry date. See Microsoft's guide to managing federation certificates.

---

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 OpenID Connect - The same setup with OpenID Connect
• User & Groups - Enabling SSO for each user