> For the complete documentation index, see [llms.txt](https://community-test.logicnets.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://community-test.logicnets.com/release-9/platform-documentation/advanced-topics/system-integration/configuring-adfs-with-logicnets.md).

# Configuring ADFS with LogicNets

## Description

This document describes how to configure Active Directory Federation Services (ADFS) and LogicNets to allow for single sign-on.

## Prerequisites

Before beginning the configuration verify that the following items are true.

* The ADFS server is reachable by end users and by the LogicNets Server via port 443 (https).
* The ADFS server is reachable by end users and the LogicNets server via the configured ADFS host names. For more information about retrieving the configured ADFS host names, go to <https://docs.microsoft.com/en-us/powershell/module/adfs/get-adfsendpoint?view=win10-ps>.
* Read through the configuration of ADFS below and ask your LogicNets Representative to confirm the required URLs.

## Configure ADFS

1. Open RDP to the ADFS server.
2. Open the ADFS Management tool.

   ![](https://2802811211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdFhfexCjZ5JMhwGzzywq%2Fuploads%2Fgit-blob-c9d711e648797e4eeee641deb36cb801d23f43b3%2F9e3ca08e-dfa3-4160-b38f-4fa1eb876490.png?alt=media)
3. Right-click on ***Application Groups*** and select ***Add Application Group***.

   ![](https://2802811211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdFhfexCjZ5JMhwGzzywq%2Fuploads%2Fgit-blob-d3d6d762d0c86e1883a4c8640ead6c037cf13626%2Fce771c90-9bc0-4e55-8423-aceb9eeb1470.png?alt=media)
4. Enter a name.
5. Select ***Server Application accessing a web-api***.
6. Click ***Next***.
7. Copy the client identifier.
8. Fill in the redirect URL of your LogicNets installation; for example, [*https://mylogicnets.mycompany.com/authentication.lns*](https://mylogicnets.mycompany.com/authentication.lns). Select ***add***.
9. Click ***Next***.
10. Select ***Generate a shared secret***.
11. Copy the secret.
12. Click ***Next***.
13. Fill in any (Relying Party) identifier; for example, [*https://mylogicnets.mycompany.com*](https://mylogicnets.mycompany.com). Make note of this, as you will need it later.

```
![](../../../.gitbook/assets/f002cdc9-85ab-4b3b-9a82-3e6258035e3a.png)
```

14. Click ***Next***.
15. Select ***Permit everyone***.
16. Click ***Next***.
17. Select the following scopes: ***allatclaims***, ***openid***, ***profile***, ***email***. When LogicNets applications call other services with the user's ADFS token, also select ***offline\_access***. This allows LogicNets to refresh that token. See the option *Bearer-pass-on token from external access provider* in [Call a Generic Webservice](/release-9/platform-documentation/process-node-parts/call-a-generic-webservice.md) for more information.
18. Click ***Next***.
19. Click ***Next***.
20. Click ***Close***.
21. Open the application group you created above.
22. Select the Web API and click ***Edit***.

```
![](../../../.gitbook/assets/3a76162e-a997-4662-9b72-2d8592055171.png)
```

23. Click *Issuance Transform Rules*.

```
![](../../../.gitbook/assets/65eb29aa-b184-4dc5-8b69-367a23da179d.png)
```

24. Click ***Add Rule***.
25. Select *Send LDAP Attributes as Claims* as template.

```
![](../../../.gitbook/assets/4d1a5a5e-1eff-4143-ba52-6db11c354d23.png)
```

26. Fill in a rule name; for example, *groupids*.
27. Select Attribute Store *Active Directory*.
28. Add mapping LDAP attribute Token-Groups as *SIDs* and Outgoing Claim Type *Group SID*.

```
![](../../../.gitbook/assets/1a15f9cf-43f9-41f9-8c34-8e07074c87ec.png)
```

29. Click ***Finish***.
30. Click ***Ok***.
31. Click ***Ok***.

After the above changes in authentication.lua and in the ADFS config the groupids are returned correctly (example below):

![](https://2802811211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdFhfexCjZ5JMhwGzzywq%2Fuploads%2Fgit-blob-5fca6834a8b173e8a39839d0b8ee7b6c6b06e9c8%2Fbb06137f-5a7e-4157-a33d-735f769d3271.png?alt=media)

### ADFS Configuration Disclaimer

Note that LogicNets does not claim expertise in the ADFS client set up. Instructions above may differ from your specific ADFS installation. While we endeavor to support the goal of setting up OAUTH, clients may need to seek online or external advice/expertise.

## Configure LogicNets

1. Open the *settings.cfg* file. This can be either the file located at ***c:\logicnets\dat\bnt\customer\settings.cfg*** (this is the company-specific settings file) or the file located at ***c:\logicnets\dat\settings.cfg*** (this is the system-wide settings file).
2. Add the following configuration to the end of the file and fill in the items noted in yellow below.

   ![](https://2802811211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdFhfexCjZ5JMhwGzzywq%2Fuploads%2Fgit-blob-aa9feec8f7642ef642ef3e8cde52049f15e78357%2Fcf4b17c0-c021-423a-bb48-477789449fde.png?alt=media)

   Note: Via PowerShell it is possible to retrieve the AD Group IDs; for example, **Get-ADGroup -Identity "Domain Users"** *or* **Get-ADGroup -Filter** retrieves info (example screenshot below) from where you can note down the SID.

   ![](https://2802811211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdFhfexCjZ5JMhwGzzywq%2Fuploads%2Fgit-blob-56ee06e9d8209bd9333034dcf88f370c52b17420%2Fbfa06038-9f82-4d9d-ac72-c4deef5929b1.png?alt=media)
3. Save the *settings.cfg* file.
4. Test whether you can log in by selecting ***Active Directory*** on the login page.

   ![](https://2802811211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdFhfexCjZ5JMhwGzzywq%2Fuploads%2Fgit-blob-89f92249b05efaca4d24132373b176958497fd3a%2F5f622c0a-0e02-460c-a829-31781d8495cc.png?alt=media)
5. Optionally, you can disable local user accounts. Local accounts are disabled by adding the follow line to your settings file: ***\_context.OAUTH\_MODES.\_local = 0***

   **CAUTION**: Disabling all local accounts may cause operational difficulties if/when your ADFS server is down. Consider retaining at least one administrative local account for this eventuality. Also, the installation folders contain an adduser script that allows the creation of a user/password on the fly

## Troubleshooting

1. If you have problems after configuring the system you can use the *LogicNets OAuth Tester Application*.
2. Make sure you have the local-user accounts enabled and you are part of the admin user group.
3. Open ***https\:////oauth-tester***.
4. Login with your local user account.
5. Select ***ADFS*** and click ***Next***.
6. Log in.
7. After you have logged in successfully you can review you can see all the information the LogicNets runtime received and interpreted.
8. OR if there is an error, the OAuth Tester should provide an error code and message. (ADFS errors are well documented on the internet, with lots of scenarios and suggestions for cause/remedial action)

### Tips

The following tips have come about from setting up ADFS via OAuth with clients in the past:

* initially do not set up any group assignments, until the basic connection is successful
* then create a single group assignment that matches one in the LogicNets User Management module and test
* then apply any desired email rules
* note that users authenticating via ADFS do not acquire additional group responsibilities given in the LogicNets User Management module. This means a user can be given different access via ADFS and via local login
* some ADFS connections do not use the auth\_parameters. If having trouble getting to the ADFS server page, try commenting these out
* use adfs for the OAUTH MODE in the settings file if "ad" is not working (it can sometimes be a reserved word)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://community-test.logicnets.com/release-9/platform-documentation/advanced-topics/system-integration/configuring-adfs-with-logicnets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.