Improve OIDC documentation (#1191)

* doc: Improve Open ID Connect documentation * doc: Document how to skip email verification * doc: Add links * doc: Update content
TheThingsIndustries · Oct 10, 2023 · cb5db5d · cb5db5d
1 parent 553b680
commit cb5db5d
Show file tree

Hide file tree

Showing 3 changed files with 194 additions and 17 deletions.
diff --git a/doc/content/reference/federated-auth/oidc.md → ...t/reference/federated-auth/oidc/_index.md b/doc/content/reference/federated-auth/oidc.md → ...t/reference/federated-auth/oidc/_index.md
@@ -2,14 +2,11 @@
 title: "OpenID Connect"
 description: ""
 distributions: ["Enterprise"]
-weight: 3
 ---
 
-## What is OpenID Connect ?
-
 [OpenID Connect](https://openid.net/connect/) 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows the Identity Server to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
 
-## What are the requirements for OpenID Connect ?
+## Requirements
 
 A new OAuth 2.0 client must be created in the provider and the client ID and client secret must be noted down. While creating the OAuth2 client, you will be asked to provide a redirect URL, which should have the following format:
 
@@ -19,7 +16,7 @@ https://thethings.example.com/oauth/login/<oidc-provider-id>/callback
 
 Replace `<oidc-provider-id>` with the ID that you have chosen for this OpenID Connect provider, for example `my-oidc-provider`.
 
-## How can I register an OpenID Connect provider ?
+## Registering an Authentication Provider
 
 We first define some user parameters used below:
 
@@ -31,22 +28,18 @@ OIDC_CLIENT_SECRET="secret123"
 OIDC_PROVIDER_URL="https://oidc.example.com"
 ```
 
-Make sure you modify these according to your setup.
-
-After you have created the OAuth2 client you may register the provider using the `is-db` stack command:
+Make sure you modify these according to your setup and use the following command to register the provider.
 
 ```bash
-tti-lw-stack is-db create-auth-provider
-    --id $OIDC_PROVIDER_ID
-    --name $OIDC_PROVIDER_NAME
-    --allow-registrations true
-    --oidc
-    --oidc.client-id $OIDC_CLIENT_ID
-    --oidc.client-secret $OIDC_CLIENT_SECRET
-    --oidc.provider-url $OIDC_PROVIDER_URL
+$ tti-lw-cli ap create $OIDC_PROVIDER_ID \
+    --name $OIDC_PROVIDER_NAME \
+    --allow-registrations true \
+    --configuration.provider.oidc.client-id $OIDC_CLIENT_ID \
+    --configuration.provider.oidc.client-secret $OIDC_CLIENT_SECRET \
+    --configuration.provider.oidc.provider-url OIDC_PROVIDER_URL
 ```
 
-## How are usernames generated for external users ?
+## Generating Usernames
 
 External users are being automatically registered when they login using the OpenID Connect provider. Their username is automatically generated based on the information provided by the provider. The following username variants are used:
 

diff --git a/doc/content/reference/federated-auth/oidc/google.md b/doc/content/reference/federated-auth/oidc/google.md
@@ -0,0 +1,84 @@
+---
+title: "Google Single Sign On"
+description: ""
+distributions: ["Enterprise"]
+---
+
+[Google's OAuth 2.0 APIs](https://developers.google.com/identity/openid-connect/openid-connect) are OpenID certified and can be used to log into {{% tts %}}.
+This page guides you with the necessary steps to login to {{% tts %}} using your Google account.
+
+<!--more-->
+
+## Prerequisites
+
+1. A [Google Cloud](https://cloud.google.com/) account with access to create credentials.
+2. A {{% tts %}} account with admin rights.
+3. The Things Stack Enterprise command line interface (`tti-lw-cli`).
+4. Choose a Provider ID (ex: `google`). It must be between 3 and 36 characters and can only contain lower-case alphanumeric letters and dashes. Multiple, leading and/or trailing dashes are not allowed.
+
+## Configuring the Provider in Google Cloud Console
+
+Log into the [Google Cloud Console](https://console.cloud.google.com) and switch to the the required project.
+
+Setup an [OAuth Consent Screen](https://console.cloud.google.com/apis/credentials/consent) if you don't have one already. Follow the instructions provided. Only the mandatory fields are required to be filled here.
+
+Create [API credentials](https://console.developers.google.com/apis/credentials) of type **Oauth Client ID**. The values are
+
+- **Application Type**: `Web Application`.
+- **Name**: A descriptive name.
+- **Redirect URL**: This should be of the form `https://<server-address>/oauth/login/<provider-id>/callback`. `server-address` is the address where {{% tts %}} is hosted.
+
+Once the client is created, Google will create a Client ID and Client Secret and will display that on the screen. Copy these values somewhere safely. You can also access these values at a later point
+
+We can now use this information to register the provider in {{% tts %}}.
+
+## Registering the Provider in The Things Stack
+
+Login to {{% tts %}} via the CLI.
+
+Register the provider. Set the following values
+
+```bash
+OIDC_PROVIDER_ID="provider ID"                  # Provider ID from above.
+OIDC_PROVIDER_NAME="My OIDC Provider"           # Name used to display on the Console.
+OIDC_CLIENT_ID="client123"                      # Client ID from the previous step.
+OIDC_CLIENT_SECRET="secret123"                  # Client Secret from the previous step.
+```
+
+```bash
+$ tti-lw-cli ap create $OIDC_PROVIDER_ID \
+    --name $OIDC_PROVIDER_NAME \
+    --allow-registrations true \
+    --configuration.provider.oidc.client-id $OIDC_CLIENT_ID \
+    --configuration.provider.oidc.client-secret $OIDC_CLIENT_SECRET \
+    --configuration.provider.oidc.provider-url https://accounts.google.com
+```
+
+Note that the ` --configuration.provider.oidc.provider-url` is hardcoded to `https://accounts.google.com`.
+
+An example response is shown below.
+
+```bash
+{
+  "ids": {
+    "provider_id": "provider ID"
+  },
+  "created_at": "2023-10-05T05:18:11.685215Z",
+  "updated_at": "2023-10-05T05:18:11.685215Z",
+  "name": "My OIDC Provider",
+  "allow_registrations": true,
+  "configuration": {
+    "oidc": {
+      "client_id": "client123",
+      "client_secret": "secret123",
+      "provider_url": "https://accounts.google.com"
+    }
+  }
+}
+```
+
+Head to the Login page of {{% tts %}} console. A button **Login to \<name\>** should be present, where `<name>` is the same as the `OIDC_PROVIDER_NAME`.
+
+Click on this button. This will redirect you to the Google Sign in page. You will be asked to authorize {{% tts %}} to read some basic user information. Select `Allow`. This is only for the first login attempt.
+
+If all your configuration is correct, you will now be redirected to {{% tts %}} console and you will be logged in. The username is chosen based on the rules explained in the [generating usernames]({{< ref "/reference/federated-auth/oidc#generating-usernames" >}}) section.
diff --git a/doc/content/reference/federated-auth/oidc/microsoft-entra.md b/doc/content/reference/federated-auth/oidc/microsoft-entra.md
@@ -0,0 +1,100 @@
+---
+title: "Microsoft Entra"
+description: ""
+distributions: ["Enterprise"]
+new_in_version: "3.28.0"
+---
+
+[Microsoft Entra](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc) supports OpenID 1.0 authorization flow and can be used to log into {{% tts %}}.
+This page guides you with the necessary steps to login to {{% tts %}} using your Microsoft Entra account.
+
+<!--more-->
+
+## Prerequisites
+
+1. A [Microsoft Entra](https://entra.microsoft.com/) account with access to create credentials.
+2. The Microsoft Entra account used to login must have an email set in their user info panel.
+3. A {{% tts %}} account with admin rights.
+4. The Things Stack Enterprise command line interface (`tti-lw-cli`).
+5. Choose a Provider ID (ex: `microsoft-entra`). It must be between 3 and 36 characters and can only contain lower-case alphanumeric letters and dashes. Multiple, leading and/or trailing dashes are not allowed.
+6. An Email ID regex that is allowed to login. For example, if you want to only allow users from your domain, the regex would be `.*@example.com`.
+
+## Disclaimer
+
+The Open ID implementation of [Microsoft Entra](https://entra.microsoft.com/) does not require the email ID of the microsoft to be verified.
+This could lead to potential security issues since the user's email is not verified.
+Admins must make sure that users who login to {{% tts %}} do not have access to update their email so that the email cannot be spoofed.
+
+## Configuring the Provider in Microsoft Entra
+
+Log in to the [Microsoft Entra admin center](https://entra.microsoft.com/).
+
+Naviagate to the [App Registrations](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps) panel.
+
+Add a new registration with the following values.
+
+- **Name**: A user-facing name.
+- **Supported account types**: **Accounts in this organizational directory only(Single Tenant)**
+- **Redirect URI**: From the dropdown choose **Web** as the type and for the value use `https://<server-address>/oauth/login/<provider-id>/callback`. `server-address` is the address where {{% tts %}} is hosted.
+
+Select **Register**.
+
+Open your app registration. Note the **Directory (tenant) ID**. This will be of the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
+
+In the registration, navigate to the **Authentication** panel. For the `Select the tokens you would like to be issued by the authorization endpoint:` section, choose `ID tokens (used for implicit and hybrid flows)`.
+
+In the **Certificates and Secrets** panel, select the **Client Secrets** tab and select **+ New Client Secret**. Add a description and an expiry date. Note the **Secret ID** and **Value**.
+
+In the **Token Configuration** tab, click **+ Add Optional Claim**, Select **ID** as the **Token type** and select the **email** field.
+
+## Registering the Provider in The Things Stack
+
+Login to {{% tts %}} via the CLI.
+
+Register the provider. Set the following values
+
+```bash
+OIDC_PROVIDER_ID="provider ID"                              # Provider ID from above.
+OIDC_PROVIDER_NAME="My OIDC Provider"                       # Name used to display on the Console.
+OIDC_CLIENT_ID="client123"                                  # Client ID is the Secret ID above.
+OIDC_CLIENT_SECRET="secret123"                              # Client Secret is the secret Value from above..
+OIDC_MICROSOFT_TENANT="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+OIDC_ALLOWED_EMAIL_REGEX=".*@example.com"                   # This is a required field to skip email verification.
+```
+
+```bash
+$ tti-lw-cli ap create $OIDC_PROVIDER_ID \
+    --name $OIDC_PROVIDER_NAME \
+    --allow-registrations true \
+    --allowed-email-regex  $OIDC_ALLOWED_EMAIL_REGEX \
+    --configuration.provider.oidc.client-id $OIDC_CLIENT_ID \
+    --configuration.provider.oidc.client-secret $OIDC_CLIENT_SECRET \
+    --configuration.provider.oidc.provider-url https://login.microsoftonline.com/$OIDC_MICROSOFT_TENANT/v2.0
+```
+
+An example response is shown below.
+
+```bash
+{
+  "ids": {
+    "provider_id": "provider ID"
+  },
+  "created_at": "2023-10-05T05:18:11.685215Z",
+  "updated_at": "2023-10-05T05:18:11.685215Z",
+  "name": "My OIDC Provider",
+  "allow_registrations": true,
+  "configuration": {
+    "oidc": {
+      "client_id": "client123",
+      "client_secret": "secret123",
+      "provider_url": "https://login.microsoftonline.com/$MICROSOFT_TENANT/v2.0"
+    }
+  }
+}
+```
+
+Head to the Login page of {{% tts %}} console. A button **Login to \<name\>** should be present, where `<name>` is the same as the `OIDC_PROVIDER_NAME`.
+
+Click on this button. This will redirect you to the Microsoft Sign in page. You will be asked to authorize {{% tts %}} to read some basic user information. Select `Allow`. This is only for the first login attempt.
+
+If all your configuration is correct, you will now be redirected to {{% tts %}} console and you will be logged in. The username is chosen based on the rules explained in the [generating usernames]({{< ref "/reference/federated-auth/oidc#generating-usernames" >}}) section.