Microsoft AD instructions - Boards (#7)

* MS AD FS instructions

* ADFS - add objectGUID to ldap claim

* Rename msadfs to msad

* LDAP docs & rename vars

* Common config for adfs

* Add AD to OAuth options

docs/boards/env/common.md

@@ -39,6 +39,8 @@ Please set the following environment variables in your config file as required
 | `user.env.CONNECTIONS_KEYCLOAK_URL`   | **Optional**: See [keycloak authentication](../connections/keycloak.md) for more information                           |
 | `user.env.CONNECTIONS_KEYCLOAK_REALM` | **Optional**: See [keycloak authentication](../connections/keycloak.md) for more information                           |
 
+---
+
 ### HCL Domino
 
 !!! tip
@@ -56,6 +58,8 @@ Please set the following environment variables in your config file as required
 | `user.env.DOMINO_AUTH_SCOPE`                    | **Optional**: defaults to `$DATA`<br>See [domino authentication](../domino/index.md) for more information                                               |
 | `user.env.DOMINO_REST_SCOPE`                    | **Optional**: defaults to `directorylookup`<br>See [domino authentication](../domino/index.md) for more information                                     |
 
+---
+
 ### HCL Digital Experience (DX)
 
 !!! tip
@@ -69,3 +73,24 @@ Please set the following environment variables in your config file as required
 | `user.env.DX_CLIENT_SECRET`      | oAuth client-secret, see [dx authentication](../dx/auth/websphere.md) for more information             |
 | `user.env.DX_ADMINS`             | **Optional**: Emails or GUIDs of users to grant admin permissions.                                     |
 | `user.env.DX_AUTH_PROVIDER_NAME` | **Optional**: name of the [OAuth Service Provider](../dx/auth/websphere.md). Defaults to `OAuthConfig` |
+
+---
+
+### Microsoft Active Directory (AD)
+
+!!! tip
+
+    **Optional**: These settings are only required if you are using Microsoft Active Directory (AD) as your authentication provider.
+
+Please follow the steps in the [Microsoft Active Directory Federation Service](../msad/index.md) guide to configure your AD FS server, and the Huddo Boards application group.
+
+| Key                                | Description                   | Example / Default                                 |
+| ---------------------------------- | ----------------------------- | ------------------------------------------------- |
+| `user.env.MSAD_NAME`               | Name on the login button      | `Microsoft AD`                                    |
+| `user.env.MSAD_FS_URL`             | AD FS server URL              | `https://adfs.example.com`                        |
+| `user.env.MSAD_CLIENT_ID`          | AD FS client id               |                                                   |
+| `user.env.MSAD_CLIENT_SECRET`      | AD FS client secret           |                                                   |
+| `user.env.MSAD_LDAP_URL`           | URL of LDAP server            | `ldap://ad.example.com`                           |
+| `user.env.MSAD_LDAP_BASE_DN`       | Base DN for LDAP search       | `DC=example,DC=com`                               |
+| `user.env.MSAD_LDAP_BIND_DN`       | Bind DN for LDAP search       | `CN=Boards,OU=Service Accounts,DC=example,DC=com` |
+| `user.env.MSAD_LDAP_BIND_PASSWORD` | Bind password for LDAP search |                                                   |

docs/boards/kubernetes/index.md

@@ -46,6 +46,7 @@ You will need to setup an OAuth application with one (or more) of these provider
 | HCL Domino      | [instructions](../domino/oauth/index.md)                                                                      | `https://[BOARDS_URL]/auth/domino/callback`      |
 | HCL DX          | [instructions](../dx/auth/websphere.md)                                                                       | `https://[BOARDS_URL]/auth/dx/callback`          |
 | Microsoft 365   | [Azure app registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) | `https://[BOARDS_URL]/auth/msgraph/callback`     |
+| Microsoft AD    | [instructions](../msad/index.md)                                                                              | `https://[BOARDS_URL]/auth/msad/callback`        |
 | Google          | [Google Console](https://console.developers.google.com/apis/credentials)                                      | `https://[BOARDS_URL]/auth/google/callback`      |
 | LinkedIn        | [LinkedIn](https://www.linkedin.com/developers/apps)                                                          | `https://[BOARDS_URL]/auth/linkedin/callback`    |
 | Facebook        | [Facebook developer centre](https://developers.facebook.com/apps/2087069981334024/fb-login/settings/)         | `https://[BOARDS_URL]/auth/facebook/callback`    |

docs/boards/msad/application-group/index.md

@@ -0,0 +1,134 @@
+# Application Group Configuration
+
+To use Microsoft AD FS as an authentication provider for Huddo Boards, you will need to configure an Application Group.
+
+1.  Open ADFS Management Console
+
+    Click `Add Application Group`
+
+    ![add](./add.png)
+
+1.  Enter a name for the Application Group
+
+    Name: `Huddo Boards`
+
+    Template: `Server application accessing a web API`
+
+    Click `Next`
+
+    ![template](./template.png)
+
+1.  Server application
+
+    !!! tip
+
+        Copy the `Client Identifier`
+
+        This will be used as the `MSAD_CLIENT_ID` in the Boards configuration and the `Identifier` set in the Web API configuration later
+
+    Set the redirect URI to `https://<BOARDS_URL>/auth/msad/callback`
+
+    For example, if your Boards URL is `https://boards.example.com`, the redirect URI would be `https://boards.example.com/auth/msad/callback`
+
+    ![server](./server.png)
+
+1.  Enable `Generate a shared secret`
+
+    !!! warning
+
+        Copy the newly generated client secret - this will not be shown again
+
+        This will be used as the `MSAD_CLIENT_SECRET` in the Boards configuration
+
+    Click `Next`
+
+    ![secret](./secret.png)
+
+1.  Web API - add the Identifier
+
+    Identifier: `<MSAD_CLIENT_ID>` (from step 3)
+
+    !!! note
+
+        This must match the Client Identifier set previously in order for the `id_token` generated at login to have additional claims and access the user name and email.
+
+    Click `Add`, then `Next`
+
+    ![web](./web.png)
+
+1.  Access Control Policy
+
+    Click `Next`
+
+    ![access-control-policy](./access-control-policy.png)
+
+1.  Select the following scopes:
+
+    -   `allatclaims` - this must be set to include all claims in the `id_token`
+    -   `openid` - required for authentication
+    -   `email` - required for the user's email
+    -   `profile` - required for the user's name
+
+    Click `Next`
+
+    ![scopes](./scopes.png)
+
+1.  Review the configration and click `Next`
+
+    ![review](./review.png)
+
+1.  Click `Close`
+
+    ![close](./close.png)
+
+1.  Right click the newly created Application Group and select `Properties`
+
+    ![newly-created](./newly-created.png)
+
+1.  Select the `Web API`
+
+    Click `Edit`
+
+    ![properties](./properties.png)
+
+1.  Click the `Issuance Transform Rules` tab
+
+    Click `Add Rule`
+
+    ![rules](./claim-rules.png)
+
+1.  Select the `Send LDAP Attributes as Claims` template
+
+    Click `Next`
+
+    ![template](./claim-template.png)
+
+1.  Configure claim rule
+
+    Name: `LDAP Attributes`
+
+    Select the attribute store - `Active Directory`
+
+    Map the LDAP attributes to outgoing claim types (type these in manually)
+
+    | LDAP Attribute     | Outgoing Claim Type |
+    | ------------------ | ------------------- |
+    | `Display-Name`     | `displayName`       |
+    | `E-Mail-Addresses` | `email`             |
+    | `objectGUID`       | `objectGUID`        |
+
+    !!! warning
+
+        The Outgoing Claim Type must be typed exactly as shown for Boards to use these values.
+
+    Click `Finish`
+
+    ![rule](./claim-rule-ldap.png)
+
+1.  Click `OK` to save the changes
+
+    ![save](./claim-ok.png)
+
+1.  Click `OK` to close the Application Group properties
+
+    ![properties-ok](./properties-ok.png)

docs/boards/msad/index.md

@@ -0,0 +1,47 @@
+# Microsoft Active Directory
+
+Microsoft AD can be used as an authentication provider for Huddo Boards when configured with the [AD Federation Service (FS)](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/ad-fs-overview).
+
+## Prerequisites
+
+1. Microsoft AD server/domain with user accounts
+1. [Microsoft AD FS deployment](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/ad-fs-deployment) accessible from the server running Boards and the users accessing Boards
+
+## Outcome
+
+Once configured, users will be able to login to Boards using their Microsoft AD credentials.
+
+![AD signin button](./signin-button.png)
+
+![ADFS login](./signin-adfs.png)
+
+## Steps
+
+1. Setup [Relying Party Trust](./relying-party-trust/index.md)
+1. Setup [Application Group Configuration](./application-group/index.md)
+
+## Configuration
+
+The steps above will provide you with the following information that you will need to configure the **user service** in Boards:
+
+| Environment Variable | Description                     | Example / Default          |
+| -------------------- | ------------------------------- | -------------------------- |
+| `MSAD_NAME`          | Name on the login button        | `Microsoft AD`             |
+| `MSAD_FS_URL`        | URL of ADFS server              | `https://adfs.example.com` |
+| `MSAD_CLIENT_ID`     | Client id from Step 2 above     |                            |
+| `MSAD_CLIENT_SECRET` | Client secret from Step 2 above |                            |
+
+#### LDAP
+
+To enable Boards to lookup user & group details from AD via LDAP, you will also need to provide the following environment variables:
+
+| Environment Variable      | Description                   | Example / Default                                 |
+| ------------------------- | ----------------------------- | ------------------------------------------------- |
+| `MSAD_LDAP_URL`           | URL of LDAP server            | `ldap://ad.example.com`                           |
+| `MSAD_LDAP_BASE_DN`       | Base DN for LDAP search       | `DC=example,DC=com`                               |
+| `MSAD_LDAP_BIND_DN`       | Bind DN for LDAP search       | `CN=Boards,OU=Service Accounts,DC=example,DC=com` |
+| `MSAD_LDAP_BIND_PASSWORD` | Bind password for LDAP search |                                                   |
+
+Example configuration:
+
+![example](./config.png)

docs/boards/msad/relying-party-trust/index.md

@@ -0,0 +1,73 @@
+# Relying Party Trust Configuration
+
+To use Microsoft AD FS as an authentication provider for Huddo Boards, you will need to configure a Relying Party Trust.
+
+1. Open ADFS Management Console
+
+    Select `Relying Party Trusts`
+
+    Click `Add Relying Party Trust`
+
+    ![add](./add.png)
+
+1. Select `Claims Aware`
+
+    Click `Start`
+
+    ![claims-aware](./claims-aware.png)
+
+1. Select `Enter data about the relying party manually`
+
+    Click `Next`
+
+    ![manual](./manual.png)
+
+1. Enter a name for the relying party trust
+
+    Name: `Relying Party`
+
+    Click `Next`
+
+    ![name](./name.png)
+
+1. If you have an **optional** token encryption certificate, select it here
+
+    Click `Next`
+
+    ![certificate](./certificate.png)
+
+1. Configure URL - neither of these protocols are required for Huddo Boards
+
+    Click `Next`
+
+    ![url](./url.png)
+
+1. Configure Identifiers - add any unique identifier for this instance. This is required by AD FS.
+
+    For example: `https://company.com/adfs/rp`
+
+    Click `Add`, then `Next`
+
+    ![identifier](./identifier.png)
+
+1. Access Control Policy
+
+    The default option is `Permit everyone`
+
+    Click `Next`
+
+    ![access-control-policy](./access-control-policy.png)
+
+1. Ready to Add Trust
+
+    Click `Next`
+
+    ![ready](./ready.png)
+
+1. Finish
+
+    Untick `Configure claims issuance policy for this application`
+
+    Click `Close`
+
+    ![finish](./finish.png)

mkdocs.yml

@@ -71,6 +71,10 @@ nav:
                   - boards/msgraph/auth/index.md
                   - Authentication: boards/msgraph/auth/index.md
                   - Teams: boards/msgraph/teams/on-prem.md
+              - Microsoft AD:
+                  - boards/msad/index.md
+                  - Relying Party Trust: boards/msad/relying-party-trust/index.md
+                  - Application Group: boards/msad/application-group/index.md
               - Related Tasks: boards/integrations/developing/related-tasks.md
           - Releases: boards/releases.md
       - Boards Hybrid: boards/hybrid.md