# ADFS

> Add Ironchip MFA to Active Directory Federation Services: install the ADFS plugin with an API key and protect your relying party trusts.

URL: https://docs.ironchip.com/en/identidad/integraciones/saas/adfs/

Ironchip integrates with ADFS (Active Directory Federation Services) through a multi-factor authentication plugin. This guide covers everything from preparing the server to testing access with Claims X-Ray.

## Requirements

- A Windows server with the Active Directory domain and federation roles.
- Access to the Ironchip admin console.
- A user with permission to configure the server.

## Configure Ironchip

Create an API Key application. You need its key when you install the plugin.

1. In the Ironchip admin console, go to **Applications** and create a new application.

   [Image: Button to create a new application in the Ironchip admin console]

2. In **Application integration type**, select **API KEY** and enter any name you like.

   [Image: New application form with the API Key type selected]

3. Copy the API key that is shown and save it for the plugin installation step.

:::caution[Save the API key]
You cannot retrieve the API key after you close the tab. Copy it and save it before you close the tab.
:::

## Configure ADFS

### Activate Active Directory

1. In **Server Manager**, open **Add Roles and Features**.
2. Add the roles **Active Directory Domain Services** and **Active Directory Federation Services**.
3. Click **Next** until you reach the end of the wizard and wait for the installation to finish. When you return to Server Manager, the two roles appear in the left menu and an alert appears in the top menu.
4. Click the alert **Promote this server to a domain controller**.
5. Select **Add a new forest** and enter the domain name you want.
6. Follow the steps to the end and click **Install**. When it finishes, you get a DNS alert that you resolve in the next section.

   [Image: Active Directory configuration wizard promoting the server to a domain controller]

### Configure DNS

1. From the administrative tools, open the DNS configuration program.
2. Right-click your server name and open **Properties**.

   [Image: Server context menu in DNS Manager with the Properties option]

3. Go to the **Forwarders** tab and add the external DNS servers you need, such as `4.2.2.1`, `4.2.2.2`, `8.8.8.8`, and `8.8.4.4`.

   [Image: Forwarders tab with the external DNS servers added]

After this, the machine restarts automatically.

### Create the SSL certificate

1. Create a self-signed certificate with this PowerShell command:

   ```powershell
   New-SelfSignedCertificate -DnsName server.ironchip.local
   ```

2. The **certlm.msc** program opens. The new certificate is in the **Personal** folder.
3. Right-click the certificate and select **Open**. On the **Details** tab, click **Copy to File**.
4. In the export wizard, select **Yes, export the private key**. Leave everything else as default and save the file, for example on the desktop.
5. Run the exported file to import it. In the window that opens, select **Local Machine**.
6. When you reach the step where you choose where to store it, select **Place all certificates in the following store**, click **Browse**, and choose the **Trusted Root Certification Authorities** folder.

### Configure the federation service

1. In Server Manager, open the alert and select **Configure the federation service on this server**.

   [Image: Server Manager alert to configure the federation service]

   The **Active Directory Federation Service Configuration Wizard** opens.

2. On the **Welcome** page, select **Create the first federation server in a federation server farm** and click **Next**.
3. On the **Connect to AD DS** page, specify an account with domain administrator rights for the Active Directory domain this computer is joined to (in this example, `ironchip.local`) and click **Next**.
4. On the **Specify Service Properties** page, do the following and click **Next**:
   - Select the SSL certificate you created earlier from the drop-down. This is the service authentication certificate.
   - For the federation service name, enter `adfs.ironchip.local`. This must match the value you used when you enrolled the SSL certificate in Active Directory Certificate Services (AD CS).
   - For the display name, enter `Ironchip Corporation`.
5. On the **Specify Service Account** page, select **Use an existing domain user account or group Managed Service Account**. For this you first need to create a dedicated user for the service, for example `service-adfs`. Then go back to the wizard and select it.
6. On the **Specify Configuration Database** page, select **Create a database on this server using Windows Internal Database** and click **Next**.
7. On the **Review Options** page, verify your selections and click **Next**.
8. On the **Pre-requisite Checks** page, verify that all checks completed successfully and click **Configure**.
9. On the **Results** page, check that the configuration completed. Four warnings appear, which you can ignore for now.

   [Image: Results page of the AD FS configuration wizard]

### Install the ADFS plugin

1. Download the plugin installer from the plugins section of the Ironchip admin console.
2. Run the installer.
3. Fill in only these fields: **Ironchip Host** (leave the default if in doubt) and **Ironchip API Key**, with the API key you got when you created the API Key application.

   [Image: ADFS plugin installer with the Ironchip Host and Ironchip API Key fields]

4. If the configuration is correct, the installer adds the plugin to AD FS and restarts the AD FS service to apply the changes.

   [Image: ADFS plugin installer after a successful installation]

### Protect an application with Ironchip MFA

The ADFS administrator interface differs between versions 3.0 and 4.0. Follow the instructions for yours. In the examples, the protected service is Claims X-Ray (see [Set up Claims X-Ray as a test application](#set-up-claims-x-ray-as-a-test-application)).

#### ADFS 3.0

1. Go to **Authentication Policies** and click **Edit Global MFA**.
2. Select **Ironchip MFA Adapter** as the multi-factor authentication method.
3. Go to **Per Relying Party Trust** and right-click the service you want to protect.
4. Click **Edit Custom Multi-factor Authentication**.
5. Enable MFA for **intranet, extranet, or both**.

Your service is now protected with Ironchip MFA.

#### ADFS 4.0

1. Go to **Service** > **Authentication Methods**. In the right-hand menu, click **Edit Multi-factor Authentication Methods**.
2. On the **Multi-factor** tab, select **Ironchip MFA Adapter**.
3. Click **Apply** and **OK**.
4. Go to **Relying Party Trusts** and select the service, for example **ClaimsXray**.
5. In the right-hand menu, click **Edit Access Control Policy**.
6. At the bottom of the window, click **Use access control policy**.
7. Select **Permit everyone and require MFA**. If you want, you can apply it only to a specific user group.
8. Click **Apply** and **OK**.

Your service is now protected with Ironchip MFA.

## Verify the integration

### Test the plugin

1. Open **Event Viewer** to see the Ironchip plugin logs.

   [Image: Windows Event Viewer]

2. If everything is correct, you see **ADFS Ironchip Plugin** in the **Applications and Services Logs** list. Open it.
3. If the plugin is installed, you see the message `Ironchip license key loaded without errors.` in the logs.

   [Image: ADFS Ironchip Plugin log in Event Viewer with the message Ironchip license key loaded without errors]

:::note
If you see the message `Unable to load IronChip license key`, check that the license is correct and try again. If the problem persists, contact Ironchip support.
:::

### Set up Claims X-Ray as a test application

Claims X-Ray is a Microsoft tool that works as a test application for ADFS.

1. Go to [https://adfshelp.microsoft.com/ClaimsXray/TokenRequest](https://adfshelp.microsoft.com/ClaimsXray/TokenRequest) and follow the instructions.
2. Open PowerShell as administrator and run the following. This adds Claims X-Ray as a relying party trust:

   ```powershell
   $authzRules = "=>issue(Type = `"http://schemas.microsoft.com/authorization/claims/permit`", Value = `"true`"); "
   $issuanceRules = "@RuleName = `"Issue all claims`"`nx:[]=>issue(claim = x); "
   $redirectUrl = "https://adfshelp.microsoft.com/ClaimsXray/TokenResponse"
   $samlEndpoint = New-AdfsSamlEndpoint -Binding POST -Protocol SAMLAssertionConsumer -Uri $redirectUrl

   Add-ADFSRelyingPartyTrust -Name "ClaimsXray" -Identifier "urn:microsoft:adfs:claimsxray" -IssuanceAuthorizationRules $authzRules -IssuanceTransformRules $issuanceRules -WSFedEndpoint $redirectUrl -SamlEndpoint $samlEndpoint
   ```

3. If you also want to add the OIDC integration, run:

   ```powershell
   Add-AdfsClient -Name "ClaimsXrayClient" -ClientId "claimsxrayclient" -RedirectUri https://adfshelp.microsoft.com/ClaimsXray/TokenResponse

   if ([System.Environment]::OSVersion.Version.major -gt 6) { Grant-AdfsApplicationPermission -ServerRoleIdentifier urn:microsoft:adfs:claimsxray -AllowAllRegisteredClients -ScopeNames "openid","profile" }
   ```

4. Check that Claims X-Ray appears under **Relying Party Trusts**.
5. If the access control policy has no parameters, right-click the service, select **Edit Access Control Policy**, delete everything, and choose the third option, **Permit everyone and MFA for specific group**. At the bottom, select the protected group.
6. Under **Authentication Methods** > **Multi-factor Authentication Methods**, check that `IronchipMFAAdapter` appears. If it doesn't, edit the list and add it.

### Enable the IdP-initiated sign-in page

1. See the endpoints of your ADFS from PowerShell:

   ```powershell
   Get-AdfsEndpoint | select FullUrl
   ```

2. In your browser, open your ADFS URL with `/idpinitiatedsignon.aspx` added at the end. You see an error because this page is disabled by default.
3. Enable it from PowerShell:

   ```powershell
   Set-AdfsProperties -EnableIdPInitiatedSignonPage $true
   ```

4. Open the page again and sign in with your user.
5. If the Windows security prompt appears, you can disable it in the **ADFS Management Console**: expand **Services**, click **Authentication Methods**, click **Edit** under **Primary Authentication Methods**, and clear the Windows prompt option. Click **Apply** and **OK**.

You now see a login form.

### Test the protected service with Claims X-Ray

1. Open the Claims X-Ray tool and configure it for your ADFS.
2. Click **Test Authentication**. You are redirected to your ADFS.
3. Enter your username and password.
4. You are prompted for MFA. Click **Submit**.
5. You receive a push notification in the Ironchip app. Open it and authenticate.

If everything is correct, you are redirected to the final Claims X-Ray page.