> For the complete documentation index, see [llms.txt](https://intuitem.gitbook.io/ciso-assistant/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://intuitem.gitbook.io/ciso-assistant/configuration/sso/identity-providers/adfs.md).

# Active Directory Federation Services (AD FS)

Configure Active Directory Federation Services (AD FS) as an Identity Provider for CISO Assistant

{% hint style="danger" %} <mark style="color:red;">For the AD FS integration described in this guide, use certificates issued by Active Directory Certificate Services (AD CS) instead of the default AD FS self-signed certificate configuration. The default configuration failed during testing with CISO Assistant, while the AD CS issued configuration worked.</mark>
{% endhint %}

Open your **Server Manager**

1. Click **Tools > AD FS Management**

   ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-af4d51bf14bc62109c3fdd551216b34014d7e70c%2Fadfs_adfs_management.png?alt=media)
2. Click **Relying Party Trust**
3. Click **Add Relying Party Trust...**

   ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-e36d5a0dc82f36a341fc395b1fda4996f14ea676%2Fadfs_add_relying_party_trust.png?alt=media)
4. A Wizard opens. Select **Claims Aware**
5. Click **Start**

   ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-63b68b156037e620d5b0505863e69214b70f0fad%2Fadfs_wizard_step_1.png?alt=media)
6. Select **Enter data about the relying party manually**
7. Click **Next >**

   ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-0f2c83efc5ba4ecd5825964f9573c664a0e238bc%2Fadfs_wizard_step_2.png?alt=media)
8. Set the **Display Name :** CISO Assistant
9. Click **Next >**

   ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-56b19314ce988064fc51cb1069f1b873ca6889ca%2Fadfs_wizard_step_3.png?alt=media)
10. Click **Next >**

    ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-afb1a53a390022a7f7d0a415c90db9310bb2256d%2Fadfs_wizard_step_4.png?alt=media)
11. Click **Enable support for the SAML 2.0 WebSSO protocol**
12. Enter the **Relying party SAML 2.0 SSO service URL:** `<base_url>/api/accounts/saml/0/acs/` (for example with localhost: `https://localhost:8443/api/accounts/saml/0/acs/`)
13. Click **Next >**

    ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-2e5175007609748ced164a4049df74a69bb55128%2Fadfs_wizard_step_5.png?alt=media)
14. For this step, open CISO Assistant, go to SSO settings and copy the **SP Entity ID** (**ciso-assistant** by default)

    ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-6150c2ffe395a4b51852a2461bb3f69582c31d07%2Fadfs_wizard_step_6.1.png?alt=media)
15. Go back to the Wizard and paste the SP Entity ID in the **Relying party trust identifier** field
16. Click **Add**
17. Click **Next >**

    ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-95e5cf59e8a8ea5f807dabdf69d5e0ca1143f03c%2Fadfs_wizard_step_6.2.png?alt=media)
18. Choose your preferred **Access Control Policy**

    <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>You can skip this step if you're in a test environment, but please keep in mind that it's strongly recommended that you configure your <strong>Access Control Policy</strong> correctly on a production server.</p></div>
19. Click **Next >**

    ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-08eaa1eb8596f97bec2375ac249073922e164ad3%2Fadfs_wizard_step_7.png?alt=media)
20. Click **Next >**

```
![](../../../.gitbook/assets/sso/adfs_wizard_step_8.png)
```

21. Click **Close**

```
![](../../../.gitbook/assets/sso/adfs_wizard_step_9.png)
```

22. A new window opens. Click **Add Rule**

```
![](../../../.gitbook/assets/sso/adfs_policy_rule_step_1.png)
```

```
<div data-gb-custom-block data-tag="hint" data-style='info'>

If for some reason this window didn't open itself automatically, go back on **AD FS Management**, click **Relying Party Trust**, right-click **CISO Assistant**, then click **Edit Claim Issuance Policy...**

![](../../../.gitbook/assets/sso/adfs_policy_rule_step_0.png)

</div>
```

23\. A Wizard opens. For **Claim rule template**, select **Send LDAP Attributes as Claims** in the drop-down menu. 24. Click **Next >**

```
![](../../../.gitbook/assets/sso/adfs_policy_rule_step_2.png)
```

25\. Set the **Claim rule name :** Main Rule 26. Select **Active Directory** in the drop-down menu for **Attribute store** 27. Fill the **Mapping of LDAP attributes to outgoing claim types** with the help of the drop-down menus:

```
| LDAP Attribute | Outgoing Claim Type |
| --- | --- |
| E-Mail-Addresses | E-Mail Address |
| User-Principal-Name | Name ID |
| Given-Name | Given Name |
| Surname | Surname |

<div data-gb-custom-block data-tag="hint" data-style='warning'>

CISO Assistant matches users by email. Without the **E-Mail Address** claim, login only works when the user's UPN is identical to their CISO Assistant email, and just-in-time provisioning cannot create accounts.

</div>
```

28\. Click **Finish**

```
![Claim rule mapping LDAP attributes to outgoing claim types](../../../.gitbook/assets/sso/adfs_policy_rule_step_3.png)
```

29\. Click **Apply** then **OK**

```
![](../../../.gitbook/assets/sso/adfs_policy_rule_step_4.png)

<div data-gb-custom-block data-tag="hint" data-style='info'>

If your CISO Assistant instance can reach AD FS, you can skip steps 30 to 45: in the SSO settings, use **Option 1: Fill the metadata url** with `https://<adfs_host>/FederationMetadata/2007-06/FederationMetadata.xml`. The metadata also follows token-signing certificate rollovers, which a pasted certificate does not.

</div>
```

30\. Go back to **AD FS Management** and click **AD FS** 31. Click **Edit Federation Service Properties...**

```
![](../../../.gitbook/assets/sso/adfs_final_step_1.png)
```

32\. A window opens. Copy the **Federation Service identifier** as it is the <mark style="color:purple;">**IdP Entity ID**</mark> in CISO Assistant

```
![](../../../.gitbook/assets/sso/adfs_final_step_2.png)
```

33\. Click **Service > Endpoints** and search for the endpoint of type **SAML 2.0/WS-Federation**. The **URL Path** of the endpoint corresponds to the end of the URL for the **SSO URL** and **SLO URL** in CISO Assistant. Combine the host name of your AD FS federation service (not your Active Directory domain name, if they differ) with this path, and use the result for both <mark style="color:purple;">**SSO URL**</mark> and <mark style="color:purple;">**SLO URL**</mark> in CISO Assistant (for example if your AD FS host is `sts.example.com`, the URL will be `https://sts.example.com/adfs/ls/`)

```
![](../../../.gitbook/assets/sso/adfs_final_step_3.png)
```

34\. Click **Service > Certificates** and double-click the primary certificate in the **Token-signing** section

```
![](../../../.gitbook/assets/sso/adfs_final_step_4.png)
```

35\. A window opens. Click on the **Details** tab 36. Click **Copy to File...**

```
![](../../../.gitbook/assets/sso/adfs_final_step_5.png)
```

37\. A Wizard opens. Click **Next** 38. If requested, select **No, do not export the private key** and click **Next**

```
![](../../../.gitbook/assets/sso/adfs_final_step_6.png)
```

39\. Select **Base-64 encoded X.509 (.CER)** and click **Next**

```
![](../../../.gitbook/assets/sso/adfs_final_step_7.png)
```

40\. Select a location to store the certificate (in your Desktop for example) by clicking on **Browse** and click **Next**

```
![](../../../.gitbook/assets/sso/adfs_final_step_8.png)
```

41\. Click **Finish**. This window should appear. Click **OK**

```
![](../../../.gitbook/assets/sso/adfs_final_step_9.png)
```

42\. Go to the location where you exported the certificate 43. Right-click the certificate and click **Open with > Choose another app** 44. Select **Notepad**. You should see something like this

```
![](../../../.gitbook/assets/sso/adfs_final_step_10.png)
```

45\. Copy everything in the file, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines, as it is the <mark style="color:purple;">**x509 certificate**</mark> in CISO Assistant

## If you get an error when logging in with SSO

It may happen that when you click on **Login with SSO** on CISO Assistant login page after completing configuration, it throws you an error. To solve this problem, go to SSO settings in CISO Assistant. In the **Advanced settings** section, check the **Allow single label domains** option. It should then work correctly.

![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-5da9ef7dd064e60e806e53319af23110ff3c07da%2Fadfs_ciso_part_1.png?alt=media)

## I want to log in from the AD FS Login Portal

{% hint style="warning" %}
Only enable this if you need it. When IdP-initiated SSO is accepted, CISO Assistant cannot tie the SAML response to a login it started, which exposes users to login CSRF: an attacker can make a victim's browser sign in to the attacker's account.
{% endhint %}

If you want to be able to log in directly from the AD FS Login Portal:

1. On the AD FS server, enable the IdP-initiated sign-on page (disabled by default) from an elevated PowerShell prompt:

   ```powershell
   Set-AdfsProperties -EnableIdpInitiatedSignonPage $true
   ```
2. Go to SSO settings in CISO Assistant. In the **Advanced settings** section, uncheck the **Reject IdP initiated SSO** option.

   ![](https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-9061be1f02e9faafe7653d518915a905993be954%2Fadfs_ciso_part_2.png?alt=media)


---

# 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://intuitem.gitbook.io/ciso-assistant/configuration/sso/identity-providers/adfs.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.