scottk/Mailu-OIDC
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/Mailu-OIDC.git synced 2025-10-29 09:12:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve GitHub user experience

Browse Source 
- Improve formatting of `AUTHORS.md`, `CONTRIBUTING.md`, `LICENSE.md`, `README.md` and `SECURITY.md`
- Update wording to include `Mailu-OIDC`-related information in `AUTHORS.md`, `CONTRIBUTING.md`, `LICENSE.md`, `README.md`, `RELEASE_TEMPLATE.md`, `SECURITY.md`
- Add OIDC setup guide to `README.md`
- Switch from issue template to issue forms
- Add pull-request templates
This commit is contained in:
Luca Bosin
2024-07-23 17:13:40 +02:00
parent c25c6df5b3
commit 32422d3f49
15 changed files with 524 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
.github/ISSUE_TEMPLATE/bug-report.yml vendored Normal file
View File

@@ -0,0 +1,108 @@
name: Bug Report
description: File a bug report to report a problem with Mailu-OIDC.
title: "`TLS_FLAVOR=notls` not working / Redirect to provider's login page broken / ..."
labels: ["bug"]
assignees: ["encotric", "wombosvideo"]
body:
- type: markdown
attributes:
value: |
## Bug Report
Thank you for opening an issue with Mailu-OIDC. Please understand that bug reports are meant for bugs only. The bug report should provide clear replication steps and logs.
Before you open your issue
- Check if no issue or pull-request for this already exists.
- Check the [Mailu-OIDC](https://github.com/heviat/Mailu-OIDC) or [Mailu](https://mailu.io/master/) documentation and [FAQ](https://mailu.io/master/faq.html). (Tip, use the search function on the Mailu documentation page)
- You understand `Mailu-OIDC` is maintained by volunteers in their **free time** — be concise, civil and accept that delays can occur.
- The title of the issue should be short and simple. It should contain specific terms related to the actual issue. Be specific while writing the title.
## Environment & Version
- type: dropdown
id: version
attributes:
label: Version
description: "Use `docker ps -a | grep mailu | awk '{print $2}' | cut -d: -f2` to get the version you are running or `grep MAILU_VERSION docker-compose.yml mailu.env` from the config file."
options:
- '2024.06'
- 'master'
- Not sure
- Not listed
validations:
required: true
- type: dropdown
id: os
attributes:
label: Operating System
multiple: true
options:
- Linux
- Windows
- Mac
- Unlisted
- type: input
id: docker-compose-version
attributes:
label: Docker Compose Version
description: Run `docker compose version` to get the version.
placeholder: ex. v2.27.1-desktop.1
validations:
required: false
- type: markdown
attributes:
value: |
If you are not using Docker Compose do not file any new issue here.
Kubernetes related issues belong to <https://github.com/Mailu/helm-charts/issues>. There is no official support for Kubernetes in `Mailu-OIDC`.
If you are not using Docker Compose or Kubernetes, create a new thread on user support in [disussions](https://github.com/Mailu/Mailu/discussions/categories/user-support).
Non-bug reports (or bug reports that do not follow the template) are moved to [disussions](https://github.com/heviat/Mailu-OIDC/discussions).
## Bug Description
- type: textarea
id: description
attributes:
label: Description
description: Explain the bug in a few words. It should be clear what the unexpected behaviour is. Share it in an easy-to-understand language.
validations:
required: true
- type: textarea
id: replication
attributes:
label: Replication Steps
description: Provide a step-by-step guide to replicate the bug. This should be clear and concise.
placeholder: ex. 1. Go to '...'
value: |
1.
2.
3.
validations:
required: true
- type: textarea
id: observed
attributes:
label: Observed Behaviour
description: What is the actual behaviour you observed?
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected Behaviour
description: What is the expected behaviour?
validations:
required: true
- type: markdown
attributes:
value: |
## Diagnostic Information
- type: textarea
id: logs
attributes:
label: Relevant log output
description: |
You can get the logs via `docker logs <container name> --tail 1000`.
For example for the admin container: `docker logs mailu_admin_1 --tail 1000`
or using docker compose `docker compose -f /mailu/docker-compose.yml logs --tail 1000 admin`
If you can find the relevant section, please share only the parts that seem relevant.
render: shell

75
.github/ISSUE_TEMPLATE/enhancement-request.yml vendored Normal file
View File

@@ -0,0 +1,75 @@
name: Enhancement Request
description: File an enhancement request to suggest improvements to existing functionality.
title: "Allow changing the OIDC login button color / Improve the setup documentation / ..."
labels: ["enhancement"]
assignees: ["encotric", "wombosvideo"]
body:
- type: markdown
attributes:
value: |
## Enhancement Request
Thank you for opening an issue with Mailu-OIDC. Please understand that enhancement requests are meant for enhancements to existing functionality only. The enhancement request should provide clear details of the enhancement and the reason for the enhancement.
Before you open your issue
- Check if no issue or pull-request for this already exists.
- Check the [Mailu-OIDC](https://github.com/heviat/Mailu-OIDC) or [Mailu](https://mailu.io/master/) documentation and [FAQ](https://mailu.io/master/faq.html). (Tip, use the search function on the Mailu documentation page)
- You understand `Mailu-OIDC` is maintained by volunteers in their **free time** — be concise, civil and accept that delays can occur.
- The title of the issue should be short and simple. It should contain specific terms related to the actual enhancement. Be specific while writing the title.
## Environment & Version
- type: dropdown
id: version
attributes:
label: Version
description: "Use `docker ps -a | grep mailu | awk '{print $2}' | cut -d: -f2` to get the version you are running or `grep MAILU_VERSION docker-compose.yml mailu.env` from the config file."
options:
- '2024.06'
- 'master'
- Not sure
- Not listed
validations:
required: true
- type: markdown
attributes:
value: |
Keep in mind that enhancements will be considered for the latest version of Mailu-OIDC. If you are not using the latest version, please upgrade before filing an enhancement request.
## Enhancement Description
- type: textarea
id: problem
attributes:
label: Related Problem
description: If your enhancement request is related to a problem, please provide a clear and concise description of what the problem is.
- type: textarea
id: improvement
attributes:
label: Improvement Description
description: Explain the enhancement in a few sentences. What should be changed or added?
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives
description: If applicable, describe any alternative solutions or features you've considered.
- type: markdown
attributes:
value: |
## Additional Information
- type: textarea
id: implementation
attributes:
label: Implementation Details
description: If you have an idea of how the enhancement could be implemented, please provide details here.
- type: textarea
id: additional
attributes:
label: Additional Context
description: Add any other context about the enhancement request here.
- type: textarea
id: screenshots
attributes:
label: Screenshots
description: If applicable, add screenshots to help explain the enhancement request. This can be a screenshot of the current behavior or a mockup of the desired behavior.

61
.github/ISSUE_TEMPLATE/feature-request.yml vendored Normal file
View File

@@ -0,0 +1,61 @@
name: Feature Request
description: File a feature request to suggest new functionality.
title: "Allow setting up multiple OIDC providers / Allow configuring OIDC from the admin panel / ..."
labels: ["enhancement"]
assignees: ["encotric", "wombosvideo"]
body:
- type: markdown
attributes:
value: |
## Feature Request
Thank you for opening an issue with Mailu-OIDC. Please understand that feature requests are meant for requesting new functionality only. The feature request should provide clear details of the new feature and the reason for the implementation.
Before you open your issue
- Check if no issue or pull-request for this already exists.
- Check the [Mailu-OIDC](https://github.com/heviat/Mailu-OIDC) or [Mailu](https://mailu.io/master/) documentation and [FAQ](https://mailu.io/master/faq.html). (Tip, use the search function on the Mailu documentation page)
- You understand `Mailu-OIDC` is maintained by volunteers in their **free time** — be concise, civil and accept that delays can occur.
- The title of the issue should be short and simple. It should contain specific terms related to the actual enhancement. Be specific while writing the title.
## Environment & Version
Keep in mind that new features will be considered for the latest version of Mailu-OIDC only. They will not be backported to older versions.
## Feature Description
- type: textarea
id: problem
attributes:
label: Related Problem
description: If your feature request is related to a problem, please provide a clear and concise description of what the problem is.
- type: textarea
id: improvement
attributes:
label: Improvement Description
description: Explain the feature in a few sentences. What should be implemented? Why is it important?
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives
description: If applicable, describe any alternative solutions or features you've considered.
- type: markdown
attributes:
value: |
## Additional Information
- type: textarea
id: implementation
attributes:
label: Implementation Details
description: If you have an idea of how the feature could be implemented, please provide details here.
- type: textarea
id: additional
attributes:
label: Additional Context
description: Add any other context about the feature request here.
- type: textarea
id: screenshots
attributes:
label: Inspirational Screenshots
description: If applicable, add screenshots to help explain the feature request. This can be a mockup of the desired behavior or screenshots from other software.

22
.github/PULL_REQUEST_TEMPLATE/bug-fix.md vendored Normal file
View File

@@ -0,0 +1,22 @@
## Bug Fix
<!-- Before creating a pull request, please make sure a related issue exists. If not, please create one first. -->
This pull request fixes the following issue(s):
<!-- Add the issues this PR fixes here. Prepend with 'closes' to auto-close referenced issues on merge. -->
- closes #000
## Details of Implementation
<!-- Describe the changes you made to fix the bug. This can be a list of commits, a short description, or a combination of both. -->
## Checklist
Before we can consider review and merge, please make sure the following list is done and checked.
- [ ] Make sure you follow our [Code of Conduct](https://github.com/heviat/Mailu-OIDC/blob/master/CODE_OF_CONDUCT.md).
- [ ] This fix is tested and works as expected.
- [ ] This fix does not break any existing functionality.
- [ ] This fix does not introduce any new functionality[^1].
- [ ] Unless it's a minor change: add a [Changelog](https://mailu.io/master/contributors/workflow.html#changelog) entry file.
[^1]: If this pull request introduces new functionality or enhances existing functionality, please create a new-feature or enhancement pull request instead.

63
.github/PULL_REQUEST_TEMPLATE/enhancement.md vendored Normal file
View File

@@ -0,0 +1,63 @@
## Enhancement
This pull request enhances the following feature(s):
<!--
Add the features this PR enhances here. If they are related to an issue, reference it, prepend with 'closes' to auto-close them on merge.
Examples:
- Add possibility to change the color of the button
- Improve setup documentation
If this PR enhances multiple features, make sure they are closely related. If not, consider creating multiple PRs.
-->
- Your enhancement here. closes #000
## Details of Implementation
### What's new
<!--
Describe the feature(s) after the enhancement.
Examples:
- The button can now be red, blue, or green
- The setup documentation now better explains the properties available
- The property `NEW_PROPERTY` is now used to configure the button label
-->
### Breaking changes
<!--
Describe any breaking changes introduced by this enhancement. If there are none, you can remove this section.
Examples:
- The button is now red by default
- The property `OIDC_ENABLED` is now **required**
- The property `SOME_PROPERTY` is renamed to `NEW_PROPERTY`
It can be helpful to provide a migration path for users to follow, which can be added to the documentation later.
-->
### Previous behavior
<!--
Describe the feature(s) before the enhancement.
Examples:
- The button was always blue
- The setup documentation was missing some steps
- The property `OIDC_ENABLED` was optional
- The property `SOME_PROPERTY` was used to configure the button label
-->
## Checklist
Before we can consider review and merge, please make sure the following list is done and checked.
- [ ] Make sure you follow our [Code of Conduct](https://github.com/heviat/Mailu-OIDC/blob/master/CODE_OF_CONDUCT.md).
- [ ] This enhancement is tested and works as expected.
- [ ] This enhancement modifies existing functionality[^1].
- [ ] This enhancement does not break any existing functionality, or breaks it intentionally (documented above).
- [ ] Add a [Changelog](https://mailu.io/master/contributors/workflow.html#changelog) entry file.
[^1]: If this pull request introduces new functionality, please create a new-feature pull request instead. If it only fixes a bug but does not otherwise modify behaviour, please create a bug-fix pull request instead.

59
.github/PULL_REQUEST_TEMPLATE/new-feature.md vendored Normal file
View File

@@ -0,0 +1,59 @@
## New Feature
This pull request adds the following feature(s):
<!--
Add the features this PR adds here. If they are related to an issue, reference it, prepend with 'closes' to auto-close them on merge.
Examples:
- Allow setting up multiple OIDC providers
- Allow setting up OIDC from the UI
If this PR adds multiple features, make sure they are closely related. If not, consider creating multiple PRs.
-->
- Your feature here. closes #000
## Details of Implementation
### What's new
<!--
Describe the feature(s) after successful implementation.
Examples:
- Multiple OIDC providers can now be set up (see guide below)
- OIDC can now be set up from the UI (see screenshots below)
-->
### Breaking changes
<!--
Describe any breaking changes introduced by this enhancement. If there are none, you can remove this section.
Examples:
- The `OIDC_PROVIDER_INFO_URL` was renamed to `OIDC_PROVIDER_INFO_URL<number>`, where `<number>` is the provider number, i.e. `OIDC_PROVIDER_INFO_URL1`
- The `OIDC_` prefixed properties were removed. Set up OIDC providers from the UI instead.
It can be helpful to provide a migration path for users to follow, which can be added to the documentation later.
-->
### Previous behavior
<!--
Describe the feature(s) before the enhancement.
Examples:
- Only one OIDC provider could be set up
- OIDC could only be set up from the `mailu.env` file
-->
## Checklist
Before we can consider review and merge, please make sure the following list is done and checked.
- [ ] Make sure you follow our [Code of Conduct](https://github.com/heviat/Mailu-OIDC/blob/master/CODE_OF_CONDUCT.md).
- [ ] This new feature is tested and works as expected.
- [ ] This new feature introduces new functionality[^1].
- [ ] This enhancement does not break any existing functionality, or breaks it intentionally (documented above).
- [ ] Unless it's a minor change: Add a [Changelog](https://mailu.io/master/contributors/workflow.html#changelog) entry file.
[^1]: If this pull request enhances existing functionality, please create an enhancement pull request instead. For bug fixes, create a bug-fix pull request instead.

5
AUTHORS.md
View File

@@ -1,6 +1,9 @@
# Contributors
Most contributors are listed on Github at: Most contributors are listed on Github at:
https://github.com/Mailu/Mailu/graphs/contributors [Mailu Contributors Graph](https://github.com/Mailu/Mailu/graphs/contributors)
and [Mailu-OIDC Contributors Graph](https://github.com/heviat/Mailu-OIDC/graphs/contributors)
If you contribute time, code or resources to the project, feel free to add If you contribute time, code or resources to the project, feel free to add
your name, pseudonym, and any contact information you feel is relevant to your name, pseudonym, and any contact information you feel is relevant to

4
CONTRIBUTING.md
View File

@@ -1,6 +1,8 @@
# Contributing to Mailu-OIDC
This project is open source, and your contributions are all welcome. There are mostly three different ways one can contribute to the project: This project is open source, and your contributions are all welcome. There are mostly three different ways one can contribute to the project:
1. use Mailu, either on test or on production instances, and report meaningful bugs when you find some; 1. use Mailu-OIDC, either on test or on production instances, and report meaningful bugs when you find some;
2. contribute code and/or configuration to the repository (see [the development guidelines](https://mailu.io/master/contributors/workflow.html) for details); 2. contribute code and/or configuration to the repository (see [the development guidelines](https://mailu.io/master/contributors/workflow.html) for details);
3. contribute localization to your native language (see [the localization docs](https://mailu.io/master/contributors/localization.html) for details); 3. contribute localization to your native language (see [the localization docs](https://mailu.io/master/contributors/localization.html) for details);

81
ISSUE_TEMPLATE.md
View File

@@ -1,81 +0,0 @@
<!--
Thank you for opening an issue with Mailu. Please understand that issues are meant for bugs only. The bug report should follow the issue template and provide clear replication steps and logs.
For **user-support questions**, reach out to us on [matrix](https://matrix.to/#/#mailu:tedomum.net) or [disussions](https://github.com/Mailu/Mailu/discussions/categories/user-support).
For anything but bug reports use the [matrix channel](https://matrix.to/#/#mailu:tedomum.net) or [disussions](https://github.com/Mailu/Mailu/discussions).
So use discussions for topics such as
* Checking announcements.
* General discussion about Mailu usage or using Mail software in general.
* Feature requests
* User support.
To be able to help you best, we need some more information.
Before you open your issue
- Check if no issue or pull-request for this already exists.
- Check [documentation](https://mailu.io/master/) and [FAQ](https://mailu.io/master/faq.html). (Tip, use the search function on the documentation page)
- You understand `Mailu` is made by volunteers in their **free time** — be concise, civil and accept that delays can occur.
- The title of the issue should be short and simple. It should contain specific terms related to the actual issue. Be specific while writing the title.
- You understand issues are only meant for bug reports that follow the issue template. Non bug reports or bug reports that do not follow the template will be moved to [disussions](https://github.com/Mailu/Mailu/discussions)
Please put your text outside of the comment blocks to be visible. You can use the button "Preview" above to check.
If you do not follow the issue template suggested below your issue may be summarily closed.
-->
## Environment & Version
- `docker compose version`
- Version: `master`
<!--
To find your version, get the image name of a mailu container and read the version from the tag (example for version 1.7).
$> docker ps -a | grep mailu
140b09d4b09c mailu/roundcube:1.7 "docker-php-entrypoi…" 2 weeks ago Up 2 days (healthy) 80/tcp
$> grep MAILU_VERSION docker-compose.yml mailu.env
-->
If you are not using docker compose do not file any new issue here.
Kubernetes related issues belong to https://github.com/Mailu/helm-charts/issues
If you are not using docker compose or kubernetes, create a new thread on user support in [disussions](https://github.com/Mailu/Mailu/discussions/categories/user-support).
Non-bug reports (or bug reports that do not follow the template) are moved to [disussions](https://github.com/Mailu/Mailu/discussions).
## Description
<!--
Further explain the bug in a few words. It should be clear what the unexpected behaviour is. Share it in an easy-to-understand language.
-->
## Replication Steps
<!--
Steps for replicating your issue
-->
## Observed behaviour
<!--
Explain or paste the result you received.
-->
## Expected behaviour
<!--
Explain what results you expected - be as specific as possible.
Just saying "it doesn’t work as expected" is not useful. It's also helpful to describe what you actually experienced.
-->
## Logs
<!--
Often it is very useful to include log fragments of the involved component.
You can get the logs via `docker logs <container name> --tail 1000`.
For example for the admin container: `docker logs mailu_admin_1 --tail 1000`
or using docker compose `docker compose -f /mailu/docker-compose.yml logs --tail 1000 admin`
If you can find the relevant section, please share only the parts that seem relevant. If you have any logs, please enclose them in code tags and in a section, like so:
```
Your logs here!
```
-->

7
LICENSE.md
View File

@@ -1,10 +1,11 @@
MIT License # MIT License
Copyright (c) 2016 All Mailu contributors at the date Copyright (c) 2024 All Mailu-OIDC or Mailu contributors at the date
This software consists of voluntary contributions made by multiple individuals. This software consists of voluntary contributions made by multiple individuals.
For exact contribution history, see the revision history available at For exact contribution history, see the revision history available at
https://github.com/Mailu/Mailu
<https://github.com/heviat/Mailu-OIDC>
Permission is hereby granted, free of charge, to any person obtaining a copy Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal of this software and associated documentation files (the "Software"), to deal

16
PULL_REQUEST_TEMPLATE.md
View File

@@ -1,16 +0,0 @@
## What type of PR?
(Feature, enhancement, bug-fix, documentation)
## What does this PR do?
### Related issue(s)
- Mention an issue like: #001
- Auto close an issue like: closes #001
## Prerequisites
Before we can consider review and merge, please make sure the following list is done and checked.
If an entry in not applicable, you can check it or remove it from the list.
- [ ] In case of feature or enhancement: documentation updated accordingly
- [ ] Unless it's docs or a minor change: add [changelog](https://mailu.io/master/contributors/workflow.html#changelog) entry file.

121
README.md
View File

@@ -1,5 +1,16 @@
<p align="leftr"><img src="docs/assets/logomark.png" alt="Mailu" height="200px"></p> <!-- markdownlint-disable MD033 MD041 MD042 -->
<p align="center">
<img src="docs/assets/logomark.png" alt="Mailu" width="128" style="vertical-align: middle" />
<span style="font-size: 4rem; margin-inline: 1rem; opacity: .8; vertical-align: middle">+</span>
<img src="docs/assets/oidc.svg" alt="OIDC" width="128" style="vertical-align: middle" />
</p>
<h1 align="center" style="border-bottom: none">Mailu-OIDC</h1>
<p align="center">
Multi-container mail server landscape<br />
featuring OpenID Connect authentication
</p>
---
Mailu is a simple yet full-featured mail server as a set of Docker images. Mailu is a simple yet full-featured mail server as a set of Docker images.
It is free software (both as in free beer and as in free speech), open to It is free software (both as in free beer and as in free speech), open to
@@ -8,12 +19,17 @@ with an easily setup, easily maintained and full-featured mail server while
not shipping proprietary software nor unrelated features often found in not shipping proprietary software nor unrelated features often found in
popular groupware. popular groupware.
Most of the documentation is available on our [Website](https://mailu.io), Most of the documentation is available [below](#getting-started), and on the [Mailu Website](https://mailu.io).
you can also [try our demo server](https://mailu.io/master/demo.html)
before setting up your own, and come [talk to us on Matrix](https://matrix.to/#/#mailu:tedomum.net).
Features > [!NOTE]
======== > This fork is extended by an OpenID Connect implementation to enable single
> sign-on user session handling and authentication using OIDC providers. The
> fork is maintained by [Heviat](https://heviat.com), a German cloud computing
> company based in Potsdam. Feel free to contribute to this repository!
## Features
![Domains](docs/assets/screenshots/domains.png)
Main features include: Main features include:
@@ -25,13 +41,98 @@ Main features include:
- **Security**, enforced TLS, DANE, MTA-STS, Letsencrypt!, outgoing DKIM, anti-virus scanner, [Snuffleupagus](https://github.com/jvoisin/snuffleupagus/), block malicious attachments - **Security**, enforced TLS, DANE, MTA-STS, Letsencrypt!, outgoing DKIM, anti-virus scanner, [Snuffleupagus](https://github.com/jvoisin/snuffleupagus/), block malicious attachments
- **Antispam**, auto-learn, greylisting, DMARC and SPF, anti-spoofing - **Antispam**, auto-learn, greylisting, DMARC and SPF, anti-spoofing
- **Freedom**, all FOSS components, no tracker included - **Freedom**, all FOSS components, no tracker included
- **Integration** with OpenID Connect providers for single sign-on
![Domains](docs/assets/screenshots/domains.png) ## Getting Started
Contributing ### Quick Overview
============
Mailu is free software, open to suggestions and contributions. All 1. Check the [Docker Compose Requirements](https://mailu.io/2024.06/compose/requirements.html)
2. Create your installation directory (e.g. `mkdir /mailu && cd /mailu`)
3. Generate a `docker-compose.yml` file and a `mailu.env` file using the
[Mailu Configuration Assistant](https://setup.mailu.io/2024.06/).
4. Replace all `mailu` docker images with `heviat/mailu-oidc` in the `docker-compose.yml` file. See [details below](#replacing-docker-images).
5. Add the [required OIDC environment variables](#setting-up-variables) to the `mailu.env` file
6. Continue with the official setup guide [from here](https://mailu.io/2024.06/compose/setup.html#tls-certificates)
### Replacing Docker Images
Every Docker image from the organization [`mailu`](https://hub.docker.com/u/mailu)
must be replaced with an image from the organization [`heviat`](https://github.com/orgs/heviat/packages)
at GitHub Container Registry - e.g. [`mailu/admin`](https://hub.docker.com/r/mailu/admin)
becomes [`ghcr.io/heviat/admin`](https://ghcr.io/heviat/admin). To do so, you
can simply place a `.env` file in the project directory and set `DOCKER_ORG`
and `MAILU_VERSION` environment variables matching our Docker images:
Example `.env` file:
```properties
DOCKER_ORG=ghcr.io/heviat
MAILU_VERSION=2024.06
```
### Setting Up Variables
To enable OpenID Connect authentication, the following additional configuration
properties are needed in `mailu.env`:
| Property Name | Description | Example |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `OIDC_ENABLED` | Enable OpenID Connect | `True` \| `False` |
| `OIDC_PROVIDER_INFO_URL` | OpenID Connect provider configuration url (aka. _well-known_ url) | [https://`host`:`port`/auth/realms/`realm`/.well-known/openid-configuration]() |
| `OIDC_REDIRECT_URL` | OpenID Connect custom redirect URL if HOSTNAME not matching your login url | [https://`host`]() |
| `OIDC_CLIENT_ID` | OpenID Connect Client ID for Mailu | `6779ef20e75817b79602` |
| `OIDC_CLIENT_SECRET` | OpenID Connect Client Secret for Mailu | `3d66bbd6d0a69af62de7...` |
| `OIDC_BUTTON_NAME` | Label text for the "login-with-OpenID" button | `OpenID Connect` |
| `OIDC_VERIFY_SSL` | Disable TLS certificate verification for the OIDC client | `True` \| `False` |
| `OIDC_CHANGE_PASSWORD_REDIRECT_ENABLED` | If enabled, OIDC users will have an button to get redirect to their OIDC provider to change their password | `True` \| `False` |
| `OIDC_CHANGE_PASSWORD_REDIRECT_URL` | Defaults to provider issuer url appended by `/.well-known/password-change`. | [https://`host`/pw-change]() |
Here is a snippet for easy copy paste:
```properties
###################################
# OpenID Connect settings
###################################
# Enable OpenID Connect. Possible values: True, False
OIDC_ENABLED=True
# OpenID Connect provider configuration URL
OIDC_PROVIDER_INFO_URL=https://<host>:<port>/auth/realms/.well-known/openid-configuration
# OpenID redirect URL if HOSTNAME not matching your login url
OIDC_REDIRECT_URL=https://mail.example.com
# OpenID Connect Client ID for Mailu
OIDC_CLIENT_ID=<CLIENT_ID>
# OpenID Connect Client secret for Mailu
OIDC_CLIENT_SECRET=<CLIENT_SECRET>
# Label text for OpenID Connect login button. Default: OpenID Connect
OIDC_BUTTON_NAME=OpenID Connect
# Disable TLS certificate verification for the OIDC client. Possible values: True, False
OIDC_VERIFY_SSL=True
# Enable redirect to OIDC provider for password change. Possible values: True, False
OIDC_CHANGE_PASSWORD_REDIRECT_ENABLED=True
# Redirect URL for password change. Defaults to provider issuer url appended by /.well-known/password-change
OIDC_CHANGE_PASSWORD_REDIRECT_URL=https://oidc.example.com/pw-change
```
### Signing In
Click on the "OpenID Connect" button[^1] on the login page to sign in with your
OpenID Connect provider. You will be redirected to the provider's login page
where you can sign in with your credentials. After successful authentication,
you will be redirected to the Mailu admin panel.
[^1]: If you don't see the "OpenID Connect" button, make sure you have set up
the OIDC environment variables correctly in the `mailu.env` file.
Use the button in the sidebar to open your mailbox on the web. Set up a user
token to sign in to external email clients like Thunderbird or Outlook. See
[Authentication tokens](https://mailu.io/2024.06/webadministration.html#authentication-tokens)
in the Mailu documentation for more information.
## Contributing
Mailu-OIDC is free software, open to suggestions and contributions. All
components are free software and compatible with the MIT license. All components are free software and compatible with the MIT license. All
specific configuration files, Dockerfiles and code are placed under the specific configuration files, Dockerfiles and code are placed under the
MIT license. MIT license.

8
RELEASE_TEMPLATE.md
View File

@@ -1,9 +1,9 @@
This is a new automatic release of Mailu. The new version can be seen in the tag name. This is a new automatic release of Mailu-OIDC. The new version can be seen in the tag name.
The main version X.Y (e.g. 2.1) will always reflect the latest version of the branch. To update your Mailu installation simply pull the latest images `docker compose pull && docker compose up -d`. The main version X.Y (e.g. 2024.06) will always reflect the latest version of the branch. To update your Mailu-OIDC installation simply pull the latest images `docker compose pull && docker compose up -d`.
The pinned version X.Y.Z (e.g. 2.1.1) is not updated. It is pinned to the commit that was used for creating this release. You can use a pinned version to make sure your Mailu installation is not suddenly updated when recreating containers. The pinned version allows the user to manually update. It also allows to go back to a previous pinned version. The pinned version X.Y.Z (e.g. 2024.06.1) is not updated. It is pinned to the commit that was used for creating this release. You can use a pinned version to make sure your Mailu installation is not suddenly updated when recreating containers. The pinned version allows the user to manually update. It also allows to go back to a previous pinned version.
To check what was changed: To check what was changed:
- Go to https://github.com/Mailu/Mailu/tree/master/towncrier/newsfragments
- Change the branch to the tag of this release. - Change the branch to the tag of this release.
- Read the news fragment files to check what was changed. - Read the news fragment files to check what was changed.

19
SECURITY.md
View File

@@ -2,17 +2,16 @@
## Supported Versions ## Supported Versions
Only the latest version is supported. When in doubt visit mailu.io or setup.mailu.io. These pages always show the current version. Only the latest version is supported. Security issues can be reported for the `master` branch as well, but it is not advised to use `master` for production purposes.
Master is the development branch. Security issues can be reported for this branch as well, but it is not advised to use master for production purposes.
| Version | Supported |
| Version | Supported | | --------------------------------------------------------------- | ---------------------- |
| ------- | ------------------ | | `master` | :white_check_mark: Yes |
| master | :white_check_mark: | | [latest release](https://github.com/heviat/Mailu-OIDC/releases) | :white_check_mark: Yes |
| current version | :white_check_mark: | | < latest version | :x: No |
| < current version | :x: |
## Reporting a Vulnerability ## Reporting a Vulnerability
Severe security issues can be reported via security @ mailu.io . Severe security issues with the OIDC implementation can be reported using the contact information on our [website](https://heviat.com/legal/imprint) or [GitHub organization page](https://github.com/heviat/).
For Minor security issues create an issue in the Mailu/Mailu repository. Other severe security issues can be reported via security @ mailu.io .
For Minor security issues [create an issue](https://github.com/Mailu/Mailu/issues/new?title=Security+issue) in the Mailu/Mailu repository.

1
docs/assets/oidc.svg Normal file
View File

@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="11.5 14.19 101.22 93.77" width="162" height="150"><path d="m552.297 576.941-120.867-56.66v646.599l120.867 56.66V576.941" style="fill:#f68712;fill-opacity:1;fill-rule:nonzero;stroke:none" transform="matrix(.13333 0 0 -.13333 0 177.333)"/><path d="M201.035 768.055c0 81.535 89.879 150.175 212.266 170.996v72.119C226.938 988.98 86.246 888.586 86.246 768.055c0-124.434 149.899-227.418 345.184-245.078v71.339c-131.563 16.825-230.395 88.211-230.395 173.739M845.395 814.102 829.52 979.555l-56.965-33.496c-54.789 32.437-124.418 55.521-202.125 64.951v-72.233c45.246-7.839 85.922-22.265 119.242-41.464l-61.836-36.356 217.559-46.855" style="fill:#bdbcbc;fill-opacity:1;fill-rule:nonzero;stroke:none" transform="matrix(.13333 0 0 -.13333 0 177.333)"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 794 B