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.

‍

Setup 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 visible only to members with the appropriate administrator permissions.

‍

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

‍

Prerequisites: Before you begin, ensure 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
  • Clarity regarding 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?
    • These two aspects are independent of each other and determine which configuration options are suitable for you in the following steps.

Step 1: Provide ADFS metadata

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

‍

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

The Metadata XML URL of your ADFS server generally 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. The important thing here is not whether the ADFS server itself can actively communicate with the internet, but 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., via 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

In the administration area, navigate to the "SSO" menu item. 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.

‍

Finally, click Save. The configuration data will be applied automatically.

Then, copy the metadata XML generated by nele.ai (4) 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.

‍

For the 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 nele.ai metadata XML URL 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 automatically imported from the XML.

‍

Continue by selecting Permit everyone and clicking 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 under 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 selected so that the window for claim rules opens automatically. If it does not open automatically, you can select the entry with a right-click and manually open Edit Claim Issuance Policy….

Step 4: Configure claim rules

Claim rules determine which user information (known as claims, e.g., email address or username) is read from Active Directory and passed to nele.ai as part of the SAML token. Two rules are required for nele.ai: one to read 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 onAdd Ruleand select the following as the rule template:Send LDAP Attributes as Claims. Click onNext.
  2. SelectAttribute storethe entryActive Directory.
  3. In the left column, select (LDAP attribute) Email addressesand in the right column (Outgoing claim type) alsoemail address.
  4. Confirm withFinish.

Next, create a second rule:

‍

  1. Click again onAdd Ruleand selectTransform an Incoming Claim. Click onNext.
  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 settingPass through all claimsand confirm withFinish.

Finally, click OK to close the editor.

Step 5: Transmit groups (mandatory 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 collectively and apply the same settings to them consistently.

‍

To do this, open the Edit Claim Issuance Policy… window again for the relevant trust relationship (if already closed: AD FS Management → Relying Party Trusts → select the relevant application → right-click and select "Edit Claim Issuance Policy…"). Click on "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.

‍

Transmitting specific individual groups

The following rule transmits 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 subsequently. 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 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 naming pattern in Rule 2 to match your specific 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 the metadata endpoint of your ADFS server 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 take place—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.