diff --git a/assets/app-registration.png b/assets/app-registration.png new file mode 100644 index 000000000..370100dba Binary files /dev/null and b/assets/app-registration.png differ diff --git a/assets/client-id.png b/assets/client-id.png new file mode 100644 index 000000000..2cdd9e9c2 Binary files /dev/null and b/assets/client-id.png differ diff --git a/assets/client-secret.png b/assets/client-secret.png new file mode 100644 index 000000000..ede92499c Binary files /dev/null and b/assets/client-secret.png differ diff --git a/assets/issuer.png b/assets/issuer.png new file mode 100644 index 000000000..80f7b3970 Binary files /dev/null and b/assets/issuer.png differ diff --git a/assets/register.png b/assets/register.png new file mode 100644 index 000000000..c1a471317 Binary files /dev/null and b/assets/register.png differ diff --git a/guides/admin/oidc-azuread.md b/guides/admin/oidc-azuread.md new file mode 100644 index 000000000..b9f8a80d7 --- /dev/null +++ b/guides/admin/oidc-azuread.md @@ -0,0 +1,111 @@ +--- +title: OpenID Connect with Azure AD +description: Learn how to use Azure's Active Directory SSO with Coder. +--- + +This article walks you through setting up single sign-on to Coder using Azure's +Active directory. + +Configuring [Coder's OpenID Connect](/docs/admin/access-control#openid-connect) +feature requires you to provide three pieces of information from Azure: + +- Client ID +- Client Secret +- Issuer + +This guide will show you how to set up Azure's Active Directory and obtain the +information you need to provide to Coder. + +## Step 1: Register your app with Azure + +1. Log in to [Azure](https://portal.azure.com/). +1. Using the search bar at the top, enter **App registrations** and click the + matching search result. + + ![App registration](../../assets/app-registration.png) + +1. Click **New registration**. +1. Provide a **Name** for your application. +1. Select the access option that best fits your needs; the **Default Directory + only - Single tenant** option should be sufficient for testing, but you may + need a **multitenant** option for production environments. + + ![Register your app](../../assets/register.png) + +1. Provide your **Redirect URL** (it will be formatted similar to + `https://coder.exampleCo.com/oidc/callback`). +1. Click **Register** to proceed. + +When Azure has created your app, you'll be redirected to **Overview**, which +displays the app information. + +## Step 2: Gather your Azure app information + +Once you've registered your app, you can obtain your: + +- Client ID +- Client Secret +- Issuer + +### Client ID + +On your application's **Overview**, look for the **Application (client) ID** +under the **Essentials** section. This is the value Coder expects as the +**Client ID**. + +![Client ID](../../assets/client-id.png) + +### Client secret + +You'll need to create the client secret. To do so: + +1. Go to **Certificates & secrets**. +1. Click **New client secret**. +1. Provide a description for your secret and set an expiration date, and click + **Add**. (We recommend creating a calendar notification to alert you shortly + before your secret is set to expire.) +1. You'll be redirected back to the **Certificates & secrets** page; save the + **Value** field string for use as your client secret. + +![Client secret value](../../assets/client-secret.png) + +### Issuer + +On your app's **Overview** page, click **Endpoints**. Find **OpenID Connect +metadata document**, and copy the first 2/3s of this value. + +![Issuer](../../assets/issuer.png) + +For example, if the full value is: + +```text +https://login.microsoftonline.com/6a8e8517-e411-4f53-a4b9-aba6f1646271/v2.0/.well-known/openid-configuration +``` + +Then remove `/.well-known/openid-configuration`, leaving the following as your +issuer: + +```text +https://login.microsoftonline.com/6a8e8...6271/v2.0 +``` + +Be sure to keep `v2.0`, though you must omit the `/` from the end. + +> If there's an issue during the configuration process, the error message will +> tell you the value you provided and the value it expected; you can use this +> information to correct your configuration. + +## Step 3: Configure Coder authentication + +Once you've saved your Azure values, you can complete the remaining steps using the +Coder UI. + +1. Log in to Coder, and go to **Manage** > **Admin** > **Authentication**. +1. In the top-most drop-down box, select **OpenID Connect**. +1. Provide the requested values for **Client ID**, **Client Secret**, and + **Issuer**. + +When done, click **Save Preferences**. + +At this point, Coder validates your configuration before proceeding. If +successful, you can expect Coder to send OIDC login attempts to Azure. diff --git a/manifest.json b/manifest.json index 6ab66be16..fdb2be61d 100644 --- a/manifest.json +++ b/manifest.json @@ -269,6 +269,9 @@ { "path": "./guides/admin/logging.md" }, + { + "path": "./guides/admin/oidc-azuread.md" + }, { "path": "./guides/admin/usage-monitoring.md" } diff --git a/package.json b/package.json index 8be193e65..9ecc28862 100644 --- a/package.json +++ b/package.json @@ -40,5 +40,8 @@ "markdownlint --config .markdownlint.jsonc --rules .markdownlint-rules --fix", "prettier --write" ] + }, + "dependencies": { + "markdownlint": "^0.23.1" } } diff --git a/yarn.lock b/yarn.lock index 449a0170b..e209d074d 100644 --- a/yarn.lock +++ b/yarn.lock @@ -726,7 +726,7 @@ markdownlint-rule-helpers@~0.14.0: resolved "https://registry.yarnpkg.com/markdownlint-rule-helpers/-/markdownlint-rule-helpers-0.14.0.tgz#4d0e1ae320e85559d8cbed1490934855791627bb" integrity sha512-vRTPqSU4JK8vVXmjICHSBhwXUvbfh/VJo+j7hvxqe15tLJyomv3FLgFdFgb8kpj0Fe8SsJa/TZUAXv7/sN+N7A== -markdownlint@~0.23.1: +markdownlint@^0.23.1, markdownlint@~0.23.1: version "0.23.1" resolved "https://registry.yarnpkg.com/markdownlint/-/markdownlint-0.23.1.tgz#98292b5d340d01e9c113f3d7fb3b2ccf89628dc2" integrity sha512-iOEwhDfNmq2IJlaA8mzEkHYUi/Hwoa6Ss+HO5jkwUR6wQ4quFr0WzSx+Z9rsWZKUaPbyirIdL1zGmJRkWawr4Q==