How do I set up single sign-on? (Using Microsoft Entra ID as an example)

With Single sign-on (SSO), your users sign in to your identity provider once and then access d.vinci without entering a password again. To make this work, two systems have to be introduced to each other: d.vinci (the service provider) and your identity provider (IdP).

This guide shows the setup using Microsoft Entra ID (formerly Azure Active Directory) as an example.

Note
Many different third-party solutions can act as an identity provider. This guide is therefore only an example and applies only to the software named here, in the state described. Microsoft changes the Entra admin center interface regularly – labels may differ slightly on your side. For authoritative information, please refer to the vendor's product documentation.

Feel free to contact us if you need support with the setup.

What you need beforehand

• In d.vinci: access to Basic Settings and to the Users administration
• In Microsoft Entra ID: at least the Cloud Application Administrator role
• The information about which attribute in Entra ID corresponds to the user name in d.vinci (see the section "The NameID has to match")

How the setup works

The setup is an exchange in both directions:

1. Create an application for d.vinci in Entra ID
2. Get the metadata from d.vinci
3. Configure SAML in Entra ID
4. Store the metadata from Entra ID in d.vinci (by URL or by file)
5. Control access to the application in Entra ID
6. Make sure the NameID that is sent matches the d.vinci user name
7. Enable SSO for the affected users in d.vinci

Step 1: Create the application in Entra ID

1. Sign in to the Microsoft Entra admin center.
2. In the left-hand navigation, open Entra ID → Enterprise apps and then All applications.

3. Click New application.
4. Click Create your own application.

5. Under What's the name of your app? enter a name, for example d.vinci SSO, select the option Integrate any other application you don't find in the gallery (Non-gallery) and click Create at the bottom.

Step 2: Get the metadata from d.vinci

1. Switch to d.vinci and open Basic Settings → SSO tab.

The tab is split into two areas: on the left the Identity Provider Configuration (which you fill in in the section "Store the IdP metadata in d.vinci"), on the right the Service Provider Information with the details your identity provider needs.

2. On the right, under Service Provider Information, open the link Service Provider Metadata XML and save the file. It has the form https://<domain-of-your-system>/plt/samlConfig/spMetadataXml.

Tip
This link can also be reached without signing in to d.vinci. So if the metadata has to be passed on to an external IT department, for example, sending the address is enough.

Step 3: Configure SAML in Entra ID

1. Back in the Entra admin center: in the application you just created, open Manage → Single sign-on and select the SAML method.

2. Click Upload metadata file at the top, select the file from d.vinci and click Add. This fills the fields under 1 Basic SAML Configuration automatically.

Alternatively you can enter Identifier (Entity ID) and Reply URL by hand; both values are contained in the metadata file from d.vinci.

3. Click Save to apply the imported configuration.
4. Scroll to the section 3 SAML Certificates and click Edit next to the Token signing certificate.

5. In the SAML Signing Certificate dialog, set Signing Option to Sign SAML response and assertion and click Save at the top.
6. In the same section, use the copy icon to copy the App Federation Metadata Url.

Step 4: Store the IdP metadata in d.vinci

There are two ways to provide your identity provider's metadata in d.vinci. We recommend the URL option.

Option A (recommended): by URL

1. Switch to d.vinci, go to Basic Settings → SSO tab and click the edit icon (pencil) next to Identity Provider Configuration. As long as no configuration is stored, it says No data available.

2. For Source, select the option URL, enter the address you copied in the section "Configure SAML in Entra ID" into the IdP Metadata XML URL field and click Update.

Caution
Changes to the configuration also affect application portals that are secured with this data via SSO.

d.vinci fetches the metadata from this address again once a day at 4:00 am. This also supports a rolling replacement of the token signing certificate: if your identity provider renews the certificate, d.vinci picks up the change automatically, without you having to do anything. Expect a delay of up to 24 hours – if you need it faster, simply click Update in the form again.

3. Check the result: after saving, the Identity Provider Configuration area is filled in and shows IdP Metadata XML, Last update, IdP Metadata XML URL, IdP Issuer/ EntityID, IdP Redirect Binding URL and IdP X.509 Certificates with their validity period. If those values are there, d.vinci has successfully read your identity provider's metadata.

Option B: by file upload

Alternatively, in the same form select the option File for Source and upload your identity provider's metadata in the IdP Metadata XML field. This makes sense, for example, if the identity provider does not offer a publicly reachable metadata URL.

Please note: the file is a snapshot. As soon as the metadata changes – in particular when the token signing certificate is replaced – you have to upload the file again manually, otherwise sign-in will fail from the moment of the change. The daily automatic update only applies to the URL option.

If your file contains more than one identity provider, d.vinci reports "The uploaded file contains more than one Identity Provider. Please select the IdP to be used for the configuration of SSO in d.vinci." In that case, select the matching IdP in the form and upload the file again.

Step 5: Control access in Entra ID

In Entra ID, the setting Assignment required? under Manage → Properties is set to Yes by default. As long as that is the case, Entra ID rejects every user who is not explicitly assigned to the application. You therefore have to implement one of the two options.

Option A: turn off assignment (simpler)

1. In the application, open Manage → Properties, set Assignment required? to No and click Save.

This means that all users in your tenant are generally allowed to use the application. Who actually has access to d.vinci is still controlled through the user administration in d.vinci – where the users are maintained anyway.

Option B: assign users and groups

1. Leave Assignment required? set to Yes and open Manage → Users and groups.
2. Click Add user/group and assign all users or groups that are supposed to use d.vinci via SSO. From then on you have to maintain this list in parallel with the user administration in d.vinci.

Which option fits is up to you and usually depends on your internal IT policies.

Step 6: The NameID has to match

d.vinci needs exactly one value from the SAML response: the NameID. It has to match the user name of the respective user in d.vinci exactly. No other claims or attributes are evaluated.

Important
SSO does not create users. d.vinci only compares the NameID against the users that already exist – anyone who is not set up in d.vinci (or whose Login enabled until date has passed) cannot sign in via SSO either. There is no automatic user provisioning from Entra ID; user administration stays in d.vinci.

Which attribute you use for this in Entra ID is your decision – common choices are the email address, the UPN or the Windows sign-in name, but it can be any other attribute as well, as long as the values match the user names in d.vinci.

By default, Entra ID supplies the attribute user.userprincipalname as the Unique User Identifier, and Name identifier format is set to Email address. If that matches your d.vinci user names, there is nothing to change here. This is how you check or change the mapping:

1. In the application, open Single sign-on, scroll to 2 Attributes & Claims and click Edit.

2. Under Required claim, click the row Unique User Identifier (Name ID).

Note
Click the row itself, not the three dots at the end of the row: for the required claim, the three-dot menu only offers Delete, and that option is greyed out.

3. In the Manage claim dialog, select the format you want under Name identifier format and, under Source attribute, the attribute that contains the d.vinci user name. Then click Save.

Example, Windows sign-in name: set Name identifier format to Default and Source attribute to user.onpremisessamaccountname.

Prerequisite for this example
The attribute user.onpremisessamaccountname has to be populated in Entra ID. It is usually created when a local Active Directory is synchronised with Entra ID (for example via Microsoft Entra Connect). Without synchronisation the attribute is empty and sign-in will fail.

Step 7: Enable SSO for the users in d.vinci

1. In d.vinci, open the Users administration and set Single Sign-on to Yes for every user who is supposed to sign in via SSO from now on.

Note
The Single Sign-on setting only appears on the user once the Identity Provider Configuration is stored. If you cannot find the field, the section "Store the IdP metadata in d.vinci" is still missing.

2. Directly above it is the setting Username/ Password. It stays in effect independently of SSO: as long as it is set to Yes, the user can still sign in with a user name and password. If you want to enforce SSO, set it to No.

Caution
Only set Username/ Password to No once sign-in via SSO has been verified to work for that user. If both settings are set to No, the user cannot sign in at all.

Afterwards, test signing in with a single user before you roll SSO out more broadly.

Good to know
For newly created users, d.vinci applies the settings automatically from now on: as soon as an Identity Provider Configuration is stored, the form has Single Sign-on set to Yes and Username/ Password set to No. So if a new user needs password sign-in, you have to change that actively.

How your users will sign in from now on

d.vinci does not redirect to the identity provider automatically. On the sign-in page, a Single Sign-on button appears in addition to signing in with a user name and password. It is only present once the Identity Provider Configuration is stored.

How prominently the button is placed depends on how many of your active users use SSO:

• The majority uses SSO: the Single Sign-on button is at the top, above the user name and password fields, and is highlighted as the primary action.
• The minority uses SSO: user name and password are at the top, the cursor is in the user name field, and the Single Sign-on button follows below the form.

The tipping point is the halfway mark: as soon as more active users use SSO than user name and password, the button moves to the top. So your users may have to scroll down first – a common reason for reports that SSO "doesn't work".

Signing out. Signing out in d.vinci only ends the d.vinci session, not the session at the identity provider – there is no single logout. Anyone who signs out and then clicks Single Sign-on again is signed straight back in, without a sign-in prompt. That is expected behaviour and not a fault. On shared devices, your users additionally have to sign out at the identity provider or close the browser window.

Two-factor authentication. The two-factor authentication in d.vinci only applies to signing in with a user name and password. Anyone signing in via SSO is not asked for an additional code – the second factor is then handled by your identity provider (with Microsoft Entra ID, for example, via MFA and Conditional Access policies). Plan for this if you have 2FA enabled in d.vinci and are switching users to SSO.

Turning SSO off again

For individual users: in the user administration, first set Username/ Password to Yes and only then set Single Sign-on to No. The order matters – if both settings are set to No at the same time, the user can no longer sign in.

For the whole system: in Basic Settings → SSO tab, click Delete in the top right and confirm the prompt. d.vinci then discards the Identity Provider Configuration including the stored metadata file. The Single Sign-on button disappears from the sign-in page, and the Single Sign-on setting is no longer visible on the user form.

Caution
Check beforehand which users have Username/ Password set to No and set those to Yes. Otherwise they will have no way to sign in after the deletion. The Single Sign-on setting itself remains stored per user and becomes visible again as soon as you store a configuration again.

In Entra ID you can then delete the enterprise application or set the method under Single sign-on to Disabled. Don't forget the application portals that may be secured with the same configuration.

If sign-in does not work

Your users see these two messages themselves when sign-in fails:

d.vinci also points out problems itself. These messages can appear:

Only users who are allowed to edit the basic settings see the two certificate warnings.