High performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.
JavaScript campaigncampaign-managementemail-marketingemail-subscriptionlistmonkmailing-listnewsletternewsletter-managementnewsletter-softwareself-hostedsms-gatewaysmtptransactional-emails
Add OIDC SSO tutorials to docs for Keycloak and authentic.
Kailash Nadhb0ecd746befd
diff --git a/docs/docs/content/oidc.md b/docs/docs/content/oidc.mdnew file mode 100644index 00000000..2013d85d--- /dev/null+++ b/docs/docs/content/oidc.md@@ -0,0 +1,77 @@++## OIDC Single Sign On++Listmonk supports single sign-on with OIDC (OpenID Connect). Any standards compliant OIDC provider can be configured in Settings -> Security -> OIDC++!!! note "Automatic user creation"+ There is no support for automatic user creation via OIDC currently. The Super Admin must create users prior in Admin -> Users with the same e-mail address that is expected from the OIDC provider per user.+++# Tutorials++Tutorials for configuring listmonk SSO with popular OIDC providers.++## Keycloak+Keycloak configuration for listmonk SSO integration.++### 1. Create a new client in Keycloak+In the Keycloak admin, use an existing realm, or create a new realm. Create a new client in `Clients → Create`.++- **General Settings**+ - **Client type**: `OpenID Connect`+ - **Client ID**: `listmonk` (or any preferred name)+ - **Name**: Optional descriptive name (e.g., "listmonk SSO")+- **Capability Config**:+ - **Client authentication**: On+ - **Authorization**: On+ - **Authentication Flow**+ - **Standard Flow**: On+ - **Direct Access grants**: On+- **Login Settings**:+ - **Root URL**: Copy the **Redirect URL for oAuth provider** value from listmonk Admin -> Settings -> Security -> OIDC. It will look like `https://listmonk.yoursite.com/auth/oidc`+ - **Valid redirect URIs**: Same as the Root URL above+ - **Valid post logout redirect URIs**: *++After the client creation steps above, go to the client's `Credentials` tab and copy the `Client Secret`.++### 2. Configure Listmonk+2. In Listmonk Admin -> Settings -> Security -> OIDC.+ - **Enable OIDC SSO**: Turn on+ - **Provider URL**: `https://keycloak.yoursite.com/auth/realms/{realm}` (replace `{realm}` with the chosen realm name)+ - **Provider name**: Set a name to show on the listmonk login form, eg: `Login with OrgName`+ - **Client ID**: Client ID set in Keycloak, eg: `listmonk`+ - **Client Secret**: Client Secret copied from Keycloak++++## Authentik+Authentik configuration for listmonk SSO integration.++### 1. Create a new OIDC provider in Authentik+In the Authentik admin interface, create a new OIDC provider for listmonk.++- **Provider Settings**:+ - **Name**: `listmonk` (or any preferred name)+ - **Signing Key**: `authentik Self-signed Certificate`+ - **Client Type**: `Confidential`+ - **Client ID**: `listmonk` (or any preferred name)+ - **Redirect URIs**: Copy the **Redirect URL for oAuth provider** value from listmonk Admin -> Settings -> Security -> OIDC. It will look like `https://listmonk.yoursite.com/auth/oidc`++After creating the provider, copy the **Client Secret**.++### 2. Create an application in Authentik+Create a new application and connect it to the newly created provider.++- **Application Settings**:+ - **Name**: `listmonk` (or any preferred name)+ - **Slug**: `listmonk` (or any preferred slug. Used in the redirect URL)+ - **Provider**: Select the OIDC provider created in the previous step++### 3. Configure listmonk+In listmonk Admin → Settings → Security → OIDC:++- **Enable OIDC SSO**: Turn on+- **Provider URL**: `https://authentik.yoursite.com/application/o/{slug}/` (replace `{slug}` with the application's slug)+- **Provider Name**: Set a name to show on the login form (e.g., `Login with OrgName`)+- **Client ID**: Client ID set in Authentik (e.g., `listmonk`)+- **Client Secret**: Client Secret copied from Authentikdiff --git a/docs/docs/mkdocs.yml b/docs/docs/mkdocs.ymlindex 32170a5f..d250a2ff 100644--- a/docs/docs/mkdocs.yml+++ b/docs/docs/mkdocs.yml@@ -54,6 +54,7 @@ nav:- "Internationalization": "i18n.md"- "Integrating with external systems": external-integration.md- "User roles and permissions": roles-and-permissions.md+ - "OIDC SSO": oidc.md- "API":- "Introduction": apis/apis.md- "SDKs and libs": apis/sdks.md