sheppy/opendesk
1
0
Fork 0
mirror of https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk.git synced 2025-12-07 16:01:37 +01:00
Code Issues Packages Projects Releases Wiki Activity

fix(helmfile): Update portal and branding.

Browse Source 
BREAKING CHANGE: Upgrading from previous releases requires manual steps, read `./docs/migrations.md` carefully.
This commit is contained in:
Thorsten Roßner
2024-10-04 09:34:39 +02:00
parent 7aee88ec94
commit 6ba6923612
52 changed files with 1805 additions and 1367 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
docs/enhanced-configuration/groupware-migration.md Normal file
View File

@@ -0,0 +1,185 @@
r<!--
SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
SPDX-License-Identifier: Apache-2.0
-->
<h1>Migration from M365 with audriga migration service and master authentication</h1>
* [Context](#context)
* [Prerequisites](#prerequisites)
* [Prepare M365 tenant for access](#prepare-m365-tenant-for-access)
* [Provisioning user accounts in openDesk](#provisioning-user-accounts-in-opendesk)
* [Deploy openDesk with master authentication](#deploy-opendesk-with-master-authentication)
* [Migration configuration](#migration-configuration)
* [Select the source provider and configure your openDesk instance](#select-the-source-provider-and-configure-your-opendesk-instance)
* [Adding accounts](#adding-accounts)
* [Add user accounts individually](#add-user-accounts-individually)
* [Add multiple user accounts via CSV file](#add-multiple-user-accounts-via-csv-file)
* [Start the migration](#start-the-migration)
* [Monitor migration status](#monitor-migration-status)
# Context
Most organizations already have email accounts on various platforms that need to be migrated to openDesk. This document describes the migration from M365 accounts to openDesk using the [audriga Migration Service](https://www.audriga.com) in combination with the master authentication option in openDesk. Other source platforms are also supported, and their migrations work in a similar manner.
The migration can be configured on audriga's self-service website, accessed with most common web browsers (e.g. IE, Firefox, Safari or Chrome). No software needs to be installed on your machine. The service connects to your mailbox similarly to what your email client does. Emails, attachments, folders, and, depending on the source systems, contacts, tasks, notes, and calendar data are being copied to your destination account. See [M365 to OX Migration Guide](https://audriga.com/fileadmin/guides/en/MS365-OX.pdf) for the scope and limitations of the process.
The data in the source mailbox will not be deleted or altered. To configure a migration, only three simple steps in audriga's self-service portal have to be completed. After the migration has started, its status can be continuously monitored on the website.
It may not be possible to complete especially large or complex migrations with only this guide. If you identify issues related to I/O, bandwidth, timeline constraints, or anything else that makes the migration more complicated than you feel comfortable handling on your own using the self-service, please get in touch with contact [audriga's support](mailto:support@audriga.com).
# Prerequisites
## Prepare M365 tenant for access
The following instructions provide information on how to authenticate Microsoft 365 / Exchange Online accounts in the audriga migration service with "modern authentication" using a service account without the need to provide a username and password for each mailbox that will be migrated.
You will have to select an existing user account that will be used as a service account for the migration. You have to register the audriga application and create an M365 email group known only to you as described in the following steps:
***1. Select one account to serve as a service account***
Please note that the account that shall serve as the service account requires a Microsoft 365/Exchange online license (mailbox).
> **Notes**<br>
> If you want to designate your admin account as a service account, you have to provide the admin with a license.
***2. Register the audriga app in your tenant***
To register the audriga app in your tenant, log into your admin account and access the following URL:
https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=3cd27a72-a19e-4945-9715-fc24d940428f&redirect_uri=https://umzug.audriga.com/SMESwitchWebApp/oauth_complete.jsp&scope=https://outlook.office.com/.default
- Accept the App "audriga CloudMovr migration"
- You will be redirected to an audriga page, which you can close without requiring additional interaction.
> **Note**<br>
> The audriga application is created under the "Enterprise application" tab in the AzureAD console.
***3. Create a "secret" group in the M365 tenant***
Create a "secret" group in the customer tenant.
- Go to <https://aad.portal.azure.com> > Azure Active Directory > Groups > New Group
- Choose a group name and group email address that includes the word "audriga" in lowercase ("Audriga" will not work), like *audriga-migration@your-maildomain.tld*
- Choose the group type "Microsoft 365"
- Appoint your service account (see 1.) as the owner of this group
## Provisioning user accounts in openDesk
In openDesk, you have to have all user accounts with mailboxes pre-defined before running the migration. You can either manually create your accounts using an IAM administrator or use the [user import tool](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/user-import) to batch import user accounts to your openDesk deployment.
## Deploy openDesk with master authentication
With openDesk 1.0 Enterprise, you can set openDesk's email components (OX AppSuite and OX Dovecot) into master authentication mode to run the migration as described in this document using the following two settings for your deployment:
```
secrets:
oxAppsuite:
adminPassword: "your_temporary_master_password"
functional:
migration:
oxAppsuite:
enabled: true
```
1. You must specify the master password referenced in the document's following sections.
2. You need to enable the actual master authentication mode.
Updating your deployment with these settings will allow you to continue with the migration scenario. Once the migration is completed, you can remove `secrets.oxAppsuite.adminPassword` and need to turn off the migration mode by setting `functional.migration.oxAppsuite.enabled` to `false` or removing that setting, as `false` is the default before you update your deployment once again.
> **Note**<br>
> For the changes to take effect, it is sufficient to deploy the `open-xchange` component.
> **Note**<br>
> While in master authentication mode, regular users cannot log in to the webmail module of openDesk or access the mail using IMAP, as it is not recommended that users interact with the target mail infrastructure during the migration scenario described in this document.
# Migration configuration
The migration is configured in 3 steps using the [audriga migration self-service](https://umzug.audriga.com/SMESwitchWebApp/?client=groupware).
Ensure you meet the prerequisites. For example, this document does not support using the standard username/password-based authentication option for M365.
## Select the source provider and configure your openDesk instance
Choose [Microsoft 365 / Exchange Online (Admin)](https://umzug.audriga.com/SMESwitchWebApp/?client=groupware#src=onmicrosoft.com) as your current provider.
> **Note**<br>
> You may need to start typing in "Microsoft Office 365/Exchange Online" for it to appear in the list.
Configure openDesk as your destination server:
- Select "Configure provider or server" in the provider selection box of the migration application.
- In the following dialog, select "Open-Xchange" as protocol.
- On the tab "IMAP"
  - For "Mailserver (host name or IP address)" enter your IMAP host, e.g. "webmail.your-opendesk-domain.tld".
  - If your IMAP server is not running on default port 993, enter your nonstandard IMAP port under Details -> Port.
  - Press check.
- On the tab "Open-Xchange"
  - Set the hostname of your OX AppSuite installation, e.g. "webmail.your-opendesk-domain.tld".
  - Press check.
- If you receive a green checkmark on both tabs, click "Save". Otherwise, check your settings until you get the green checkmark.
## Adding accounts
You can add accounts one by one, which seems only feasible for test scenarios, or when you migrate a handful of mailboxes, or you can add accounts using CSV upload. Both options are described in the following subsections.
### Add user accounts individually
By default, you will enter the "Add Mailbox" tab where you can add individual accounts for M365:
```
Username:             enter the username of the service account, e.g. eva@your-maildomain.tld
Password:             enter the particular group email address, e.g. audriga-migration@your-maildomain.tld
Details -> mailbox:   enter the user's mailbox you want to migrate, e.g. pia@your-maildomain.tld
```
On the openDesk site, please provide:
```
Username:             enter the username of the mailbox you want to migrate to, e.g. pia@your-maildomain.tld
Password:             enter the master password
```
Click on check to verify the credentials. If the data is correct, a green checkmark will appear. A red cross will be displayed if the credentials need to be corrected.
After checking and confirming, you can use the same procedure to add further mailboxes.
Alternatively, you can add multiple accounts via CSV upload. Find information in the following.
### Add multiple user accounts via CSV file
Prepare a CSV file with all necessary information. Unsurprisingly, this is the same information as described in the "Add User Accounts Individually" section above.
The CSV requires the following column order with a closing semicolon after the last value - but no headline is expected; the first line must be your migration data already:
```
M365ServiceAccount;M365GroupEmailAddress;M365Mailbox;openDeskMailbox;openDeskMasterPassword;
```
Example CSV:
```
eva@your-maildomain.tld;audriga-migration@your-maildomain.tld;eva@your-maildomain.tld;eva;YourMasterPassword;
eva@your-maildomain.tld;audriga-migration@your-maildomain.tld;max@your-maildomain.tld;max;YourMasterPassword;
eva@your-maildomain.tld;audriga-migration@your-maildomain.tld;pia@your-maildomain.tld;pia;YourMasterPassword;
eva@your-maildomain.tld;audriga-migration@your-maildomain.tld;ida@your-maildomain.tld;ida;YourMasterPassword;
```
Select the "Add multiple accounts" tab to configure up to 50 user accounts by uploading a CSV file. If you need to migrate more accounts, you can execute the migration multiple times.
Click "Check" and save afterwards.
## Start the migration
You will see a summary of the migration, including the number of accounts and the amount of data. Even if the analysis of the source accounts has not yet been completed, you can proceed.
Ensure you have a valid voucher; otherwise, you must complete the payment process.
Press "Start Migration" to proceed.
## Monitor migration status
The migration process may take some time to start. For large amounts of data, it may take a couple of hours.
Click on "Details" to get further information about the migration.
You can access a detailed log for each account by clicking "Protocol" on the right-hand side. Here, you can see detected duplicates or encountered errors (e.g., if emails cannot be transferred due to your provider's size limitations).
You will receive status emails for the migration job's submission and start, as well as when the migration job is finished. The emails are sent to the email address you have entered during the configuration. Those emails include a link to the status website so you can easily track and monitor your migration. Once the migration has been started, you can safely close the status website and shut down your computer; the migration will continue. You can re-open the status website anytime.

80
docs/enhanced-configuration/idp-federation.md
View File

@@ -20,109 +20,107 @@ SPDX-License-Identifier: Apache-2.0
# Context
Most organizations already have an Identity and Access Management (IAM) of their own that includes an identity provider (IdP) for single-sign-on to internal or external web applications.
Most organizations already have an Identity and Access Management (IAM) system with an identity provider (IdP) for single sign-on to internal or external web applications.
This document shows how to configure your organizations IdP as well as the openDesk IdP to allow account federation to support single-sign-on to openDesk based on your organization's login.
This document shows how to configure your organization's IdP and the openDesk IdP to support account federation with openDesk single sign-on based on your organization's login.
# Prerequisites
## User accounts
Beside the configuration it is required that the user accounts with the same name exist within openDesk. This prerequisite is outside the scope of this document.
We will provide additional documents regarding user provisioning in the future, so here's just an overview regarding potential scenarios:
In addition to the configuration, it is required that user accounts with the same name exist within openDesk. While this prerequisite is outside the scope of this document, the following approaches are feasible:
- Manual user management
- That is a lightweight way for testing your IdP federation setup or in case you just have a small amount of users to manage.
- Just create and maintain you user(s) in openDesk and ensure the username in your IAM and openDesk is identical.
- A lightweight option to test your IdP federation setup or if you have only a small number of users to manage.
- Create and maintain your user(s) in openDesk and ensure the username in your IAM and openDesk is identical.
- User import
- If you need to create more than just a couple of test accounts you can use the [openDesk User Importer](https://gitlab.opencode.de/bmi/opendesk/tooling/user-import) that utilizes the UDM REST API for user account creation.
- If you need to create more than just a couple of test accounts, you can use the [openDesk User Importer](https://gitlab.opencode.de/bmi/opendesk/components/platform-development/images/user-import) that utilizes the UDM REST API for user account creation.
- Downsides: Managing groups and deleting accounts needs to be done manually.
- Automated Pre-provisioning:
- Pre-provisioning users and groups including de-provisioning (deleting) accounts is the best practice as it ensures that openDesk is in sync with your organization's IAM.
- Pre-provisioning users and groups, including de-provisioning (deleting) accounts, is the best practice to ensure that openDesk is in sync with your organization's IAM.
- There are at least two ways of implementing the pre-provisioning:
- UDM REST API:
- Build a provisioning solution by yourself using the [UDM REST API](https://docs.software-univention.de/developer-reference/5.0/en/udm/rest-api.html).
- The API gives you full control over the contents of the IAM in order to create, update or delete users and groups.
- Build a provisioning solution using the [UDM REST API](https://docs.software-univention.de/developer-reference/5.0/en/udm/rest-api.html).
- The API gives you complete control over the contents of the IAM to create, update, or delete users and groups.
- Nubus Directory Importer:
- It is based on a Python one-way directory synchronization for users and groups.
- Please find more details in the [upstream product's documentation](https://docs.software-univention.de/nubus-kubernetes-operation/latest/en/howto-connect-external-iam.html).
- Ad-hoc provisioning (AHP)
- This feature is currently not available in the openDesk Keycloak, but there are plans by the Supplier Univention to make it available.
- Ad-hoc provisioning creates an user account on the fly during a users first login.
- While AHP this is a nice approach for a quick start with openDesk it has various downsides:
- Users are just created after their first login, so you cannot find your colleagues in the openDesk apps unless they already logged in.
- This feature is currently unavailable in openDesk's Keycloak, but Univention plans to make it available in the future.
- Ad-hoc provisioning creates a user account on the fly during a user's first login.
- While ad-hoc provisioning is an excellent approach for a quick start with openDesk, it has various downsides:
- Users are created after their first login, so you cannot find your colleagues in the openDesk apps unless they have already logged in.
- A user account would never be deactivated or deleted in openDesk.
- Group memberships are not transferred.
## External IdP with OIDC
This document focusses on the OIDC federation between an external IdP and the openDesk IdP. It makes use of the OpenID Connect (OIDC) protocol, so your external IdP must support OIDC.
This document focuses on the OIDC federation between an external IdP and the openDesk IdP. It uses the OpenID Connect (OIDC) protocol, so your external IdP must support OIDC.
# Example configuration
## Versions
The example was tested with openDesk v0.7.0 using its integrated Keycloak v24.0.3, as external IdP we also used an openDesk deployment of the same version but created a separate realm for proper separation of the configuration.
The example was tested with openDesk v0.7.0 using its integrated Keycloak v24.0.3. As external IdP, we also used an openDesk deployment of the same version but created a separate realm for proper configuration separation.
## Example values
The following values are used in this example documentation. Please ensure when you come across such a value even if it is part of a URL hostname or path that you adapt it where needed to your setup:
The following values are used in this example documentation. Please ensure when you come across such a value, even if it is part of a URL hostname or path, that you adapt it where needed to your setup:
- `idp.organization.tld`: hostname for your organization's IdP
- `id.opendesk.tld`: hostname for the openDesk IdP, so openDesk is obviously deployed at `opendesk.tld`
- `fed-test-idp-realm`: realm name for your organizations IdP
- `opendesk-federation-client`: OIDC client for the openDesk federation that is defined in your organizations IdP
- `auto-federate-idp`: Identifier of your organizations IdP's configuration within the openDesk Keycloak.
- `idp.organization.tld`: hostname for your organization's IdP.
- `id.opendesk.tld`: hostname for the openDesk IdP, so openDesk is deployed at `opendesk.tld`.
- `fed-test-idp-realm`: realm name for your organization's IdP.
- `opendesk-federation-client`: OIDC client for the openDesk federation defined in your organization's IdP.
- `auto-federate-idp`: Identifier of your organization IdP's configuration within the openDesk Keycloak.
- `auto-federate-flow`: Identifier of the required additional login flow to be created and referenced in the openDesk Keycloak.
## Keycloak admin console access
To access the admin console of Keycloak in an openDesk deployment you need to add a route for `/admin` to the Keycloak's ingress. This is done automatically if you deploy openDesk with `debug.enabled: true` but beware that this will also cause a lot of log output across all openDesk pods.
To access Keycloak's admin console in an openDesk deployment, you must add a route for `/admin` to the Keycloak's ingress. This is done automatically if you deploy openDesk with `debug.enabled: true`, but beware that this will also cause a lot of log output across all openDesk pods.
The admin console will be available at:
- Organization's IdP: https://idp.organization.tld/admin/master/console/
- openDesk IdP: https://id.opendesk.tld/admin/master/console/
For the following configuration steps login with user `kcadmin` and grab the password from the `ums-keycloak` pod's `KEYCLOAK_ADMIN_PASSWORD` variable.
For the following configuration steps, log in with user `kcadmin` and grab the password from the `ums-keycloak` pod's `KEYCLOAK_ADMIN_PASSWORD` variable.
## Your organizations IdP
As we use the Keycloak of another openDesk instance to simulate your organization's IdP in this example, especially URL paths within the Keycloak might differ if you use different products.
In this example, we use the Keycloak of another openDesk instance to simulate your organization's IdP. However, URL paths differ if you use another product.
Please let us know about your experiences or differences you came across.
### Separate realm
To not interfere with an existing configuration for our test scenario we create a separate realm:
To not interfere with an existing configuration for our test scenario, we create a separate realm:
- `Create realm` (from realm selection drop down menu in the left upper corner)
- `Create realm` (from the realm selection drop-down menu in the left upper corner)
- *Realm name*: `fed-test-idp-realm`
- `Create`
### OIDC Client
If you just created the `fed-test-idp-realm` your are already in the admin screen for the realm, if not use the realm selection drop down menu in the left upper corner to switch to the realm.
If you just created the `fed-test-idp-realm`, you are already in the admin screen for the realm; if not, use the realm selection drop-down menu in the upper left corner to switch to the realm.
- *Clients* > *Create Client*
- Client create wizard page 1:
- *Client type*: `OpenID Connect`
- *Client-ID*: `opendesk-federation-client`
- *Name*: `openDesk @ your organization` (is the descriptive text of the client that might show up in you IdP's UI and therefore should explain what the client is used for)
- *Name*: `openDesk @ your organization` (is the descriptive text of the client that might show up in your IdP's UI and therefore should explain what the client is used for)
- Client create wizard page 2:
- *Client authentication*: `On`
- *Authorization*: `Off` (default)
- *Authentication flow*: leave defaults
- `Standard flow`
- `Direct access grants`
- `Standard flow`
- `Direct access grants`
- Client create wizard page 3:
- *Valid Redirect URLs*: `https://id.opendesk.tld/realms/opendesk/broker/auto-federate-idp/endpoint`
- When completed with *Save* you get to the detailed client configured that also needs some updates:
- When completed with *Save*, you get to the detailed client configured that also needs some updates:
- Tab *Settings* > Section *Logout settings*
- *Front channel logout*: `Off`
- *Back channel logout URL*: `https://id.opendesk.tld/realms/opendesk/protocol/openid-connect/logout/backchannel-logout`
- Tab *Credentials*
- Copy the *Client Secret* as we need it for the configuration of the openDesk IdP to be used in the openDesk IdP, as well as the *Client-ID*.
- Copy the *Client Secret* and the *Client-ID* as we need them to configure the openDesk IdP.
## openDesk IdP
@@ -137,20 +135,20 @@ The following configuration is taking place in the Keycloak realm `opendesk`.
- *Identity providers* > *User-defined* > *OpenID Connect 1.0*
- *Alias*: `auto-federate-idp` (used in our example)
- *Display Name*: Descriptive Name in case you do not forcefully redirect the user to the IdP that name is shown in the login screen for manual selection.
- *Display Name*: A descriptive Name, in case you do not forcefully redirect the user to the IdP, that name is shown on the login screen for manual selection.
- *Use discovery endpoint*: `On` (default)
- *Discovery endpoint*: `https://idp.organization.tld/realms/fed-test-idp-realm/.well-known/openid-configuration` - this URL may look different if you do not use Keycloak or a different Keycloak version as IdP in your organization
- In case the IdP metadata could not be auto-discovered you will get an error.
- If everything is fine you can review the discovered metadata for your IdP by clicking on *Show metadata*.
- You will get an error if the IdP metadata cannot be auto-discovered.
- If everything is fine, you can review the discovered metadata for your IdP by clicking on *Show metadata*.
- *Client authentication*: `Client secret sent as post` (default)
- *Client ID*: Use the client ID you took form your organization's IdP config (`opendesk-federation-client` in this example)
- *Client Secret*: Use the secret you took form your organization's IdP config
- When completed with *Add* you get to the detailed IdP configured that also needs some updates (you may need to open the *Advanced* section to access some settings)
- *Client ID*: Use the client ID you took from your organization's IdP config (`opendesk-federation-client` in this example)
- *Client Secret*: Use the secret you took from your organization's IdP config
- When completed with *Add*, you get to the detailed IdP configured that also needs some updates (you may need to open the *Advanced* section to access some settings)
- *Back-channel logout*: `On`
- *Disable user info*: `On`
- *First login flow override*: `auto-federate-flow`
- In case you want to forcefully redirect all users to your organizations IdP (disabling login with local openDesk accounts):
- In case you want to forcefully redirect all users to your organization's IdP (disabling login with local openDesk accounts):
- *Authentication* > `2fa-browser`
- Click on the cogwheel next to the *Identity Provider Re-director*
- *Alias*: `auto-federate-idp`

29
docs/enhanced-configuration/matrix-federation.md
View File

@@ -6,20 +6,20 @@ SPDX-License-Identifier: Apache-2.0
<h1>Matrix federation</h1>
<!-- TOC -->
* [Use case](#use-case)
* [Context](#context)
* [Example configuration](#example-configuration)
* [Disable federation](#disable-federation)
* [Separate Matrix domain](#separate-matrix-domain)
<!-- TOC -->
# Use case
# Context
The Element chat application and its server component Synapse are based on the Matrix protocol,
that supports federation with other Matrix servers to communicate with the users with accounts on these servers.
By default, you can chat with users that have an account within your openDesk installation and federate with other
By default, you can chat with users who have an account within your openDesk installation and federate with other
matrix-based servers.
Federation support can be disabled.
Federation support can be turned off.
# Example configuration
@@ -28,36 +28,35 @@ Please ensure when you come across such a value,
even if it is part of a URL hostname or path, that you adapt it where needed to your setup:
- `opendesk.domain.tld`: the mandatory `DOMAIN` setting for your deployment resulting in
`https://chat.opendesk.domain.tld` to access the Element chat.
`https://chat.opendesk.domain.tld` for access to the Element chat.
- `my_organization.tld`: an optional alternative domain used for mail and/or Matrix.
If not used it is also set to `opendesk.domain.tld`.
It is also set to `opendesk.domain.tld` if not used.
## Disable federation
The following setting can disable federation:
The following setting can turn off federation:
```yaml
functional:
externalServices:
matrix:
federation:
enabled: false
  externalServices:
    matrix:
      federation:
        enabled: false
```
## Separate Matrix domain
If you want to federate with other Matrix instances and use a separate Matrix domain, you need to provide a JSON file on
the Matrix domain to use delegation.
This is not included inside openDesk.
the Matrix domain to use delegation. It is not part of your openDesk deployment.
Domain path: `https://my_organization.tld/.well-known/matrix/server`
Content:
```JSON
{
"m.server": "matrix-federation.opendesk.domain.tld:443"
    "m.server": "matrix-federation.opendesk.domain.tld:443"
}
```
More detailed information can be found in Matrix/Synapse documentation:
[Matrix Delegation](https://matrix-org.github.io/synapse/v1.98/delegate.html)
[Matrix Delegation](https://element-hq.github.io/synapse/latest/delegate.html)

44
docs/enhanced-configuration/separate-mail-matrix-domain.md
View File

@@ -3,9 +3,9 @@ SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlic
SPDX-License-Identifier: Apache-2.0
-->
<h1>Separate domains for mail and or matrix</h1>
<h1>Separate domains for mail and or Matrix </h1>
* [Use case](#use-case)
* [Context](#context)
* [Example configuration](#example-configuration)
* [Mail domain](#mail-domain)
* [Matrix domain](#matrix-domain)
@@ -14,24 +14,24 @@ SPDX-License-Identifier: Apache-2.0
* [Content Security Policy](#content-security-policy)
* [.well-known](#well-known)
# Use case
# Context
As communication over mail and chat can go beyond the borders of your openDesk installation you may want to use different domains for the mail and/or matrix.
As communication over mail and chat can go beyond the borders of your openDesk installation, you may want to use different domains for the mail and/or Matrix.
# Example configuration
The following values are used in this example documentation. Please ensure when you come across such a value even if it is part of a URL hostname or path that you adapt it where needed to your setup:
The following values are used in this example documentation. Please ensure when you come across such a value, even if it is part of a URL hostname or path, that you adapt it where needed to your setup:
- `opendesk.domain.tld`: the mandatory `DOMAIN` setting for your deployment resulting in `https://mail.opendesk.domain.tld` to access emails and `https://chat.opendesk.domain.tld` to access the Element chat that is based on the Matrix protocol.
- `my_organization.tld`: the alternative domain used for mail and/or Matrix.
## Mail domain
By default all email addresses in openDesk are created based on the `DOMAIN` you specified for your deployment. In our example resulting in the users having `<username>@opendesk.domain.tld` as mail addresses. In case you prefer the users to send and receive emails with another domain you can set that one using the optional `MAIL_DOMAIN` in the deployment:
By default, all email addresses in openDesk are created based on the `DOMAIN` you specified for your deployment. In our example, the users have `<username>@opendesk.domain.tld` as their mail addresses. In case you prefer the users to send and receive emails with another domain, you can set that one using the optional `MAIL_DOMAIN` in the deployment:
```yaml
global:
mailDomain: "my_organization.tld"
  mailDomain: "my_organization.tld"
```
or via environment variable
@@ -40,21 +40,21 @@ or via environment variable
export MAIL_DOMAIN=my_organization.tld
```
This of course requires the MX record for the domain to point to the mail host for your openDesk deployment. Optionally add the SPF and DMARC records.
Of course, this requires the domain's MX record to point to the mail host for your openDesk deployment. You can optionally add the SPF and DMARC records.
| Record name | Type | Value |
| Record name                | Type | Value                                            |
| -------------------------- | ---- | ------------------------------------------------ |
| my_organization.tld | MX | `10 mail.opendesk.domain.tld` |
| my_organization.tld | TXT | `v=spf1 +a +mx +a:mail.opendesk.domain.tld ~all` |
| _dmarc.my_organization.tld | TXT | `v=DMARC1; p=quarantine` |
| my_organization.tld        | MX   | `10 mail.opendesk.domain.tld` |
| my_organization.tld        | TXT  | `v=spf1 +a +mx +a:mail.opendesk.domain.tld ~all` |
| _dmarc.my_organization.tld | TXT  | `v=DMARC1; p=quarantine` |
## Matrix domain
Similar to the specific domain for email addresses you may want to specify a domain that differs from your deployment's default `DOMAIN` to define your users Matrix IDs. Use the `MATRIX_DOMAIN` to do so:
Similar to the specific domain for email addresses, you may want to specify a domain that differs from your deployment's default `DOMAIN` to define your user's Matrix IDs. Use the `MATRIX_DOMAIN` to do so:
```yaml
global:
matrixDomain: "my_organization.tld"
  matrixDomain: "my_organization.tld"
```
or via environment variable
@@ -67,17 +67,17 @@ export MATRIX_DOMAIN=my_organization.tld
The following changes apply to the standard DNS:
| Record name | Type | Value | Comment |
| -------------------------------- | ---- | -------------------------------------- | ---------------------------------------------------------------------------------- |
| _matrix._tcp.my_organization.tld | SRV | `1 10 PORT matrix.opendesk.domain.tld` | `PORT` is your NodePort/LoadBalancer port of `opendesk-synapse-federation` service |
| Record name | Type | Value | Comment |
| -------------------------------- | ---- | -------------------------------------- | -------------------------------------------------------------------------------------- |
| _matrix._tcp.my_organization.tld | SRV | `1 10 PORT matrix.opendesk.domain.tld` | `PORT` is your NodePort/LoadBalancer port of the `opendesk-synapse-federation` service |
*Note:* `matrix.opendesk.domain.tld` in the "Value" column can also be the IP address where synapse TLS port is listening to.
*Note:* `matrix.opendesk.domain.tld` in the "Value" column can also be the IP address synapse TLS port listens to.
### Webserver
#### Content Security Policy
The webserver of `my_organization.tld` should add `*.opendesk.domain.tld` to its CSP header.
The `my_organization.tld` webserver should add `*.opendesk.domain.tld` to its CSP header.
#### .well-known
@@ -89,11 +89,11 @@ you need to create a JSON file with the following contents that is served from
```json
{
"m.homeserver": {
"base_url": "https://matrix.opendesk.domain.tld"
  "m.homeserver": {
    "base_url": "https://matrix.opendesk.domain.tld"
}
}
```
This ensures clients know where to find the Matrix protocol endpoint when users specify `my_organization.tld`
The above configuration ensures clients know where to find the Matrix protocol endpoint when users specify `my_organization.tld`
as their homeserver.