Information for users
Information for administrators
Trivia

Setting up automatic login with ADFS

Overview

General information

What is ADFS?

Active Directory Federation Services (ADFS) is a service provided by Microsoft that enables Single Sign-On (SSO) across organizational boundaries. It acts as an Identity Provider (IdP) that passes user identities from your organization's Active Directory to external applications like nele.ai as SAML tokens—without the need to transmit passwords.

‍

Setting this up requires advanced knowledge of SAML 2.0, single sign-on, and your identity provider. Once initialized as described here, login can be configured via the nele.ai administration area under "SSO". Since the user and administration areas are integrated into the same application, this section is only visible to members with the appropriate administrator permissions.

‍

Members who automatically receive a nele.ai account via single sign-on are not automatically deleted or deactivated. These members can be removed manually via the member management section if necessary.

‍

Prerequisites: Before you begin, ensure that the following requirements are met:

‍

  • A running ADFS server (recommended: Windows Server 2012 or newer)
  • Administrative access to both the ADFS server and the nele.ai administration area
  • A valid SSL certificate for your ADFS instance
  • Clarifying your ADFS network topology:
    • Is the metadata endpoint accessible from the internet (e.g., via a Web Application Proxy)?
    • Can the ADFS server itself access external URLs via outbound traffic?
    • These two aspects are independent of each other and determine which configuration options are available to you in the following steps.

Step 1: Provide ADFS metadata

Before configuring nele.ai, you will need the metadata from your ADFS server.

‍

If your ADFS metadata endpoint is accessible from the internet (recommended):

The metadata XML URL for your ADFS server typically follows this pattern:

‍

https://[your-adfs-server]/federationmetadata/2007-06/federationmetadata.xml

‍

Make a note of this URL – you will need it in the next step. It is not important whether the ADFS server itself can actively communicate with the internet, but rather that nele.ai, as an external service, can reach this endpoint from the outside (e.g., via a Web Application Proxy/AD FS Proxy or an appropriate firewall rule).

‍

Note: You can verify that the metadata is correct and accessible from the outside by opening this URL in a browser from a device outside your internal network (e.g., using a mobile data connection). If configured correctly, an XML file will be displayed. If an error message appears or the page is unreachable, please contact your server administrator.

‍

If the metadata endpoint is not accessible from the outside:

Export the metadata XML file directly from your ADFS server and have it ready for upload.

Step 2: nele.ai – Configure SSO and retrieve metadata XML

Navigate to the SSO menu item in the administration area. There, under the configuration types (1), select the option that matches your environment:

‍

Configuration via metadata XML URL (2) (recommended):

Enter the metadata XML URL of your ADFS server that you noted in step 1. This option is only available if your ADFS server's metadata endpoint is accessible from the internet. This method is recommended because nele.ai automatically retrieves the metadata at regular intervals, allowing it to handle certificate renewals without manual intervention (see the note at the end of this document).

‍

Configuration via metadata XML file (3):‍

If the metadata endpoint is not accessible from the outside, upload the metadata XML file exported in step 1 directly instead. Please note that in this case, no automatic updates will take place, and the file must be re-uploaded manually whenever certificates are changed.

‍

Then click Save. The configuration data will be applied automatically.

‍

Copy the metadata XML (4) generated by nele.ai or its URL – you will need this for the subsequent configuration on the ADFS side.

Step 3: ADFS – Setting up the Relying Party Trust

A Relying Party Trust is the entry in ADFS that defines which external application (in this case: nele.ai) is trusted and which user information may be shared with it.

‍

Go to your ADFS server and open the AD FS Management console. Navigate to the Relying Party Trusts folder and right-click to create a new entry. A configuration wizard will open – click Next.

‍

Under Data source, select the import option that matches your environment:

‍

If the ADFS server can access the nele.ai URL via an outbound connection:

‍

Import data about the relying party published online or on a local network – Enter the metadata XML URL for nele.ai that you copied in step 2. This option requires the ADFS server itself to have an outbound internet connection and is independent of whether the ADFS metadata endpoint is accessible from the outside.

‍

If no outbound connection is possible:

‍

Import data about the relying party from a file – Select the downloaded metadata XML file from nele.ai.

‍

Click Next and enter a descriptive name for the new entry under Display name, e.g., nele.ai. Click Next again – the remaining settings will be imported automatically from the XML.

‍

Next, select Permit everyone and click Next.

‍

Note: This setting initially grants access to all users. If you wish to restrict access to specific Active Directory groups, this access rule can be adjusted later by right-clicking the entry and selecting Edit Access Control Policy.

‍

You can review your settings on the subsequent summary screens. In the final step, leave the checkbox for Open the Edit Claim Issuance Policy dialog for this relying party trust when the wizard closes selected so that the window for the claim rules opens automatically. If it does not open automatically, you can right-click the entry and select Edit Claim Issuance Policy… to open it manually.

Step 4: Configure claim rules

Claim rules determine which user information (known as claims, e.g., email address or username) is retrieved from Active Directory and passed on to nele.ai as part of the SAML token. Two rules are required for nele.ai: one to retrieve the email address and one to convert it into the expected SAML format (Name ID).

‍

In the claim rules window, first create an initial rule:

‍

  1. Click Add Rule and select the following as the rule template: Send LDAP Attributes as Claims. Click Next.
  2. Under Attribute store the entry Active Directory .
  3. In the left column, select (LDAP attribute) Email addresses and in the right column (Outgoing claim type) also Email address .
  4. Confirm by clicking Finish.

Then create a second rule:

‍

  1. Click again on Add rule and this time select Transform an incoming claim. Click on Next.
  2. Configure the following settings:
    1. Incoming claim type: E-Mail Address
    2. Outgoing claim type: Name ID
    3. Outgoing Name ID format: Emaill
  3. Keep the default setting Pass through all claims and confirm with Finish.

Finally, click OK to close the editor.

Step 5: Transmit groups (Required step)

To ensure users are assigned to the correct SSO groups during automatic login, a separate rule for group transmission must be set up in addition to the claim rules from step 4. SSO groups allow you to manage users in the nele.ai administration area in bulk and apply the same settings to them consistently.

‍

To do this, reopen the Edit Claim Issuance Policy… window for the relevant trust relationship (if already closed: AD FS Management → Relying Party Trusts → select the relevant application → select "Edit Claim Issuance Policy…" on the right). Click "Add Rule" and select "Send Claims Using a Custom Rule" as the template. Give the rule a descriptive name and paste the appropriate rule text.

‍

Targeted transmission of individual groups

The following rule is used to transmit a single, specifically selected group based on its SID:

‍

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "ID of the group to be transmitted"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", Value = c.Value, Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, ValueType = c.ValueType);

‍

Replace ID of the group to be transmitted with the actual SID of the desired Active Directory group. In this case, the SID itself is transmitted and displayed in the nele.ai administration area.

‍

If you would prefer to transmit a meaningful, custom name instead of the SID, use the following variant:

‍

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "ID of the group to be transmitted"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", Value = "Name for transmission");

‍

Transmitting multiple groups based on a name pattern

‍

Alternatively, you can transmit all of a user's groups and filter them afterwards. This requires two consecutive rules:

‍

Rule 1 – initially transfers all of the user's groups into an intermediate value:

‍

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => add(store = "Active Directory", types = ("http://tmp/groups"), query = ";tokenGroups;{0}", param = c.Value);

‍

Rule 2 – restricts the transmission to groups whose names match a specific pattern. In the following example, only groups starting with "nele-" are transmitted:

‍

c:[Type == "http://tmp/groups", Value =~ "^(?i)nele-"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups", Value = c.Value);

‍

Adjust the name pattern in Rule 2 to match your own group naming convention in Active Directory.

‍

Finally, click OK to close the editor and save the configured rules.

Completion and testing

You can test a successful configuration using the login URL in the SSO section of the administration area. Access this URL; if set up correctly, you will be redirected to your identity provider, where you can log in with your credentials.

‍

After a successful login, you will be redirected to an overview page where you can choose, among other things, whether you want to log in to the desktop app or the web app. Alternatively, you can download nele.ai for various operating systems there.

‍

Note on certificate renewal: nele.ai can only update certificates automatically if your ADFS server's metadata endpoint is permanently accessible from the internet (configured via Metadata XML URL, see steps 1 and 2). If the metadata XML file was uploaded manually instead, no automatic update will occur—in this case, the certificates will eventually expire and users will no longer be able to log in. Resolve this in good time by either re-importing the current metadata XML from nele.ai into ADFS or by re-uploading the current metadata XML from your ADFS server into nele.ai.