Existing Secrets

<!--
SPDX-FileCopyrightText: 2025 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
SPDX-License-Identifier: Apache-2.0
-->

<h1>Existing Secrets</h1>

This document covers how to utilise existing secrets and special requirements. The examples documented here are mostly showing the format with the openDesk default values.

<!-- TOC -->
* [General](#general)
* [Components](#components)
  * [Cassandra](#cassandra)
  * [Keycloak](#keycloak)
  * [MinIO](#minio)
  * [Notes](#notes)
  * [OpenProject](#openproject)
  * [XWiki](#xwiki)
<!-- TOC -->

# General

⚠ ATTENTION: This feature is still in early development. For now you can't simply replace plain secrets with existing secrets because some secrets are used several components where some maybe don't support existing secrets by now.

For most components when set the existing secret will supersede e.g. a password in a `values.yaml` file.

The file [`existing_secrets.yaml`](/helmfile/environments/default/existing_secrets.yaml.gotmpl) lists all possible references to existing secrets that are currently implemented in openDesk.

# Components

This section covers information and special requirements to existing secrets that some Helm Charts expect.

## Cassandra

Cassandra is pre-populated with information regarding Dovecot with a `cql` script. The openDesk default `initDB` setting is configured as follows:

```yaml
  initUserData.cql: >
    CREATE KEYSPACE IF NOT EXISTS {{ .Values.databases.dovecotDictmap.name | quote }} WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };
    CREATE ROLE IF NOT EXISTS {{ .Values.databases.dovecotDictmap.username | quote }};
    ALTER ROLE {{ .Values.databases.dovecotDictmap.username | quote }} WITH PASSWORD = {{ regexReplaceAll "'" .Values.secrets.cassandra.dovecotDictmapUser "''" | squote }} AND LOGIN = true;
    GRANT ALL ON KEYSPACE {{ .Values.databases.dovecotDictmap.name | quote }} TO {{ .Values.databases.dovecotDictmap.username | quote }};
    CREATE KEYSPACE IF NOT EXISTS {{ .Values.databases.dovecotACL.name | quote }} WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };
    CREATE ROLE IF NOT EXISTS {{ .Values.databases.dovecotACL.username | quote }};
    ALTER ROLE {{ .Values.databases.dovecotACL.username | quote }} WITH PASSWORD = {{ regexReplaceAll "'" .Values.secrets.cassandra.dovecotACLUser "''" | squote }} AND LOGIN = true;
    GRANT ALL ON KEYSPACE {{ .Values.databases.dovecotACL.name | quote }} TO {{ .Values.databases.dovecotACL.username | quote }};
```

This has to be adapted into a secret that also holds a `cql` script and is named in `initDBSecret`.

## Keycloak

Several existing secrets utilised by the Keycloak bootstrap chart are expected in a special format and/or key.

### Admin credentials

```yaml
stringData:
  admin.yaml: |
    username: "kcadmin"
    password: "{{ .Values.secrets.keycloak.adminPassword }}"
```

### ox-connector

The secret `openxchangeConnector.provisioningApiPassword` has to provide a JSON file. The value `.Values.secrets.oxConnector.provisioningApiPassword` is taken from the default openDesk install without existing secrets and has to be replaced by some secret value. The following format is expected:

```yaml
    stringData:
      ox-connector.json: "{ \"name\": \"ox-connector\", \"realms_topics\": [{\"realm\": \"udm\", \"topic\": \"oxmail/oxcontext\"}, {\"realm\": \"udm\", \"topic\": \"oxmail/accessprofile\"}, {\"realm\": \"udm\", \"topic\": \"users/user\"}, {\"realm\": \"udm\", \"topic\": \"oxresources/oxresources\"}, {\"realm\": \"udm\", \"topic\": \"groups/group\"}, {\"realm\": \"udm\", \"topic\": \"oxmail/functional_account\"}], \"request_prefill\": true, \"password\": \"{{ .Values.secrets.oxConnector.provisioningApiPassword }}\" }"
```

### LDAP Search

The secret `nubus.ldapSearch.keycloak` has the requirement to use `password` as key.

### SSOFederation and Clients

Values taken from those existing secrets will supersede secret values that are already present for the `client`/`IdP` in the configuration or add them accordingly. Further the secrets for the have to provide a `yaml` file in a special format. Both formats rely on the same key as used in the configuration respectively. The expected format for each configuration can be seen in the table below:

|Section                                              |Format       |
|-----------------------------------------------------|-------------|
|`functional.authentication.clients`                  |1.           |
|`functional.authentication.ssoFederation.idpDict`    |2.           |
|`keycloak.clients`                                   |1.           |

1. Expected format for the `clients` secrets:
 
    ```yaml
    opendesk-intercom:
      clientId: "opendesk-intercom"
      secret: "{{ .Values.secrets.keycloak.clientSecret.intercom }}"
    opendesk-notes:
      clientId: "opendesk-notes"
      secret: "{{ .Values.secrets.keycloak.clientSecret.notes }}"
    opendesk-dovecot:
      clientId: "opendesk-dovecot"
      secret: "{{ .Values.secrets.keycloak.clientSecret.dovecot }}"
    opendesk-oxappsuite:
      clientId: "opendesk-oxappsuite"
      secret: "{{ .Values.secrets.keycloak.clientSecret.as8oidc }}"
    opendesk-matrix:
      clientId: "opendesk-matrix"
      secret: "{{ .Values.secrets.keycloak.clientSecret.matrix }}"
    opendesk-nextcloud:
      clientId: "opendesk-nextcloud"
      secret: "{{ .Values.secrets.keycloak.clientSecret.ncoidc }}"
    opendesk-openproject:
      clientId: "opendesk-openproject"
      secret: "{{ .Values.secrets.keycloak.clientSecret.openproject }}"
    opendesk-xwiki:
      clientId: "opendesk-xwiki"
      secret: "{{ .Values.secrets.keycloak.clientSecret.xwiki }}"
    ```

2. Expected format for the `ssoFederation` secret:

    ```yaml
    yourIdpDictEntry:
      clientId: "yourSecretValueHere"
      clientSecret: "yourSecretValueHere"
    ```

## MinIO

Like described in the [upstream `values.yaml`](https://github.com/bitnami/charts/blob/main/bitnami/minio/values.yaml#L1595) credentials and information about a user in existing secrets listed in `usersExistingSecrets` have to be formatted as follows:

```yaml
stringData:
  username1: |
    username=test-username
    password=test-password
    disabled=false
    policies=readwrite,consoleAdmin,diagnostics
    setPolicies=false
```

Further we need the credentials introduced at MinIO in various other components that didn't implement the special format from MinIO. Hence we have to create key-value-pairs of the passwords for them.

## Notes

There are some values that consist of more than just one secret part.

```yaml
backend:
  configuration:
    django:
      superuserEmail:
        value: {{ printf "default.admin@%s" .Values.global.domain | quote }}
    redisUrl:
      value: "redis://default:{{ .Values.cache.notes.password | default .Values.secrets.redis.password }}@{{ .Values.cache.notes.host }}:{{ .Values.cache.notes.port }}/7"
```

## OpenProject

Here we need a custom secret to inject confidential data into environment variables as expected by OpenProject.

```yaml
stringData:
  OPENPROJECT_SEED__ENTERPRISE__TOKEN: {{ .Values.enterpriseKeys.openproject.token | quote }}
  OPENPROJECT_SEED_LDAP_OPENDESK_BINDPASSWORD: {{ .Values.secrets.nubus.ldapSearch.openproject | quote }}
  OPENPROJECT_AUTHENTICATION_GLOBAL__BASIC__AUTH_USER: {{ .Values.secrets.openproject.apiAdminUsername | quote }}
  OPENPROJECT_AUTHENTICATION_GLOBAL__BASIC__AUTH_PASSWORD: {{ .Values.secrets.openproject.apiAdminPassword | quote }}
  OPENPROJECT_SOUVAP__NAVIGATION__SECRET: {{ .Values.secrets.centralnavigation.apiKey | quote }}
  OPENPROJECT_SMTP__PASSWORD: {{ .Values.secrets.postfix.opendeskSystemPassword | quote }}
```

## XWiki

Properties listed in the file of the existing secret will overwrite plain values.

Licenses can also be given via properties and require the format `licenses=<EnterpriseLicense>,<Applicationslicense>`.

Like described in the [upstream `values.yaml`](https://github.com/xwiki-contrib/xwiki-helm/blob/master/charts/xwiki/values.yaml#L435) credentials and information about a user in existing secrets listed in `propertiesSecret` have to be formatted as follows:

```yaml
stringData:
  propertiesFile: |
    propertie1=propertie1Value
    propertie2=propertie2Value
    propertie3=propertie3Value
```