diff --git a/docs/boards/env/common.md b/docs/boards/env/common.md index 2d9109b11..de1c3583f 100644 --- a/docs/boards/env/common.md +++ b/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`
See [domino authentication](../domino/index.md) for more information | | `user.env.DOMINO_REST_SCOPE` | **Optional**: defaults to `directorylookup`
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 | | diff --git a/docs/boards/kubernetes/index.md b/docs/boards/kubernetes/index.md index 0c848627c..e41917416 100644 --- a/docs/boards/kubernetes/index.md +++ b/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` | diff --git a/docs/boards/msad/application-group/access-control-policy.png b/docs/boards/msad/application-group/access-control-policy.png new file mode 100644 index 000000000..64548b27a Binary files /dev/null and b/docs/boards/msad/application-group/access-control-policy.png differ diff --git a/docs/boards/msad/application-group/add.png b/docs/boards/msad/application-group/add.png new file mode 100644 index 000000000..18cf5e1a7 Binary files /dev/null and b/docs/boards/msad/application-group/add.png differ diff --git a/docs/boards/msad/application-group/claim-ok.png b/docs/boards/msad/application-group/claim-ok.png new file mode 100644 index 000000000..ca243fe03 Binary files /dev/null and b/docs/boards/msad/application-group/claim-ok.png differ diff --git a/docs/boards/msad/application-group/claim-rule-ldap.png b/docs/boards/msad/application-group/claim-rule-ldap.png new file mode 100644 index 000000000..3310c5625 Binary files /dev/null and b/docs/boards/msad/application-group/claim-rule-ldap.png differ diff --git a/docs/boards/msad/application-group/claim-rules.png b/docs/boards/msad/application-group/claim-rules.png new file mode 100644 index 000000000..e980b45d4 Binary files /dev/null and b/docs/boards/msad/application-group/claim-rules.png differ diff --git a/docs/boards/msad/application-group/claim-template.png b/docs/boards/msad/application-group/claim-template.png new file mode 100644 index 000000000..9f0db5c7e Binary files /dev/null and b/docs/boards/msad/application-group/claim-template.png differ diff --git a/docs/boards/msad/application-group/close.png b/docs/boards/msad/application-group/close.png new file mode 100644 index 000000000..de22eaab0 Binary files /dev/null and b/docs/boards/msad/application-group/close.png differ diff --git a/docs/boards/msad/application-group/index.md b/docs/boards/msad/application-group/index.md new file mode 100644 index 000000000..60abcf26d --- /dev/null +++ b/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:///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: `` (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) diff --git a/docs/boards/msad/application-group/newly-created.png b/docs/boards/msad/application-group/newly-created.png new file mode 100644 index 000000000..12d2b04ea Binary files /dev/null and b/docs/boards/msad/application-group/newly-created.png differ diff --git a/docs/boards/msad/application-group/properties-ok.png b/docs/boards/msad/application-group/properties-ok.png new file mode 100644 index 000000000..613c49469 Binary files /dev/null and b/docs/boards/msad/application-group/properties-ok.png differ diff --git a/docs/boards/msad/application-group/properties.png b/docs/boards/msad/application-group/properties.png new file mode 100644 index 000000000..afe3947ce Binary files /dev/null and b/docs/boards/msad/application-group/properties.png differ diff --git a/docs/boards/msad/application-group/review.png b/docs/boards/msad/application-group/review.png new file mode 100644 index 000000000..b2b73862a Binary files /dev/null and b/docs/boards/msad/application-group/review.png differ diff --git a/docs/boards/msad/application-group/scopes.png b/docs/boards/msad/application-group/scopes.png new file mode 100644 index 000000000..4c32eac47 Binary files /dev/null and b/docs/boards/msad/application-group/scopes.png differ diff --git a/docs/boards/msad/application-group/secret.png b/docs/boards/msad/application-group/secret.png new file mode 100644 index 000000000..4db7f061f Binary files /dev/null and b/docs/boards/msad/application-group/secret.png differ diff --git a/docs/boards/msad/application-group/server.png b/docs/boards/msad/application-group/server.png new file mode 100644 index 000000000..3416fb9c0 Binary files /dev/null and b/docs/boards/msad/application-group/server.png differ diff --git a/docs/boards/msad/application-group/template.png b/docs/boards/msad/application-group/template.png new file mode 100644 index 000000000..feecbc287 Binary files /dev/null and b/docs/boards/msad/application-group/template.png differ diff --git a/docs/boards/msad/application-group/web.png b/docs/boards/msad/application-group/web.png new file mode 100644 index 000000000..8ad375a15 Binary files /dev/null and b/docs/boards/msad/application-group/web.png differ diff --git a/docs/boards/msad/config.png b/docs/boards/msad/config.png new file mode 100644 index 000000000..030e80eaa Binary files /dev/null and b/docs/boards/msad/config.png differ diff --git a/docs/boards/msad/index.md b/docs/boards/msad/index.md new file mode 100644 index 000000000..f2f1f3c87 --- /dev/null +++ b/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) diff --git a/docs/boards/msad/relying-party-trust/access-control-policy.png b/docs/boards/msad/relying-party-trust/access-control-policy.png new file mode 100644 index 000000000..7e0273c0b Binary files /dev/null and b/docs/boards/msad/relying-party-trust/access-control-policy.png differ diff --git a/docs/boards/msad/relying-party-trust/add.png b/docs/boards/msad/relying-party-trust/add.png new file mode 100644 index 000000000..8e9b277f2 Binary files /dev/null and b/docs/boards/msad/relying-party-trust/add.png differ diff --git a/docs/boards/msad/relying-party-trust/certificate.png b/docs/boards/msad/relying-party-trust/certificate.png new file mode 100644 index 000000000..da5e30495 Binary files /dev/null and b/docs/boards/msad/relying-party-trust/certificate.png differ diff --git a/docs/boards/msad/relying-party-trust/claims-aware.png b/docs/boards/msad/relying-party-trust/claims-aware.png new file mode 100644 index 000000000..4b8d6f101 Binary files /dev/null and b/docs/boards/msad/relying-party-trust/claims-aware.png differ diff --git a/docs/boards/msad/relying-party-trust/finish.png b/docs/boards/msad/relying-party-trust/finish.png new file mode 100644 index 000000000..17ae0cb40 Binary files /dev/null and b/docs/boards/msad/relying-party-trust/finish.png differ diff --git a/docs/boards/msad/relying-party-trust/identifier.png b/docs/boards/msad/relying-party-trust/identifier.png new file mode 100644 index 000000000..bb950ed5e Binary files /dev/null and b/docs/boards/msad/relying-party-trust/identifier.png differ diff --git a/docs/boards/msad/relying-party-trust/index.md b/docs/boards/msad/relying-party-trust/index.md new file mode 100644 index 000000000..82b383553 --- /dev/null +++ b/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) diff --git a/docs/boards/msad/relying-party-trust/manual.png b/docs/boards/msad/relying-party-trust/manual.png new file mode 100644 index 000000000..505e23cad Binary files /dev/null and b/docs/boards/msad/relying-party-trust/manual.png differ diff --git a/docs/boards/msad/relying-party-trust/name.png b/docs/boards/msad/relying-party-trust/name.png new file mode 100644 index 000000000..1b0c3f648 Binary files /dev/null and b/docs/boards/msad/relying-party-trust/name.png differ diff --git a/docs/boards/msad/relying-party-trust/ready.png b/docs/boards/msad/relying-party-trust/ready.png new file mode 100644 index 000000000..0efef8da0 Binary files /dev/null and b/docs/boards/msad/relying-party-trust/ready.png differ diff --git a/docs/boards/msad/relying-party-trust/url.png b/docs/boards/msad/relying-party-trust/url.png new file mode 100644 index 000000000..5c9f419cb Binary files /dev/null and b/docs/boards/msad/relying-party-trust/url.png differ diff --git a/docs/boards/msad/signin-adfs.png b/docs/boards/msad/signin-adfs.png new file mode 100644 index 000000000..16db457a9 Binary files /dev/null and b/docs/boards/msad/signin-adfs.png differ diff --git a/docs/boards/msad/signin-button.png b/docs/boards/msad/signin-button.png new file mode 100644 index 000000000..7196793da Binary files /dev/null and b/docs/boards/msad/signin-button.png differ diff --git a/mkdocs.yml b/mkdocs.yml index e369b5fb6..7ae489692 100644 --- a/mkdocs.yml +++ b/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