Secrets providers
Last modified 08 Mar 2024 17:10 +01:00

Secrets providers are the new way to obtain secrets in midPoint. They are configured in system configuration and can be used in configuration objects in two ways:

  1. Protected strings

    New container externalData with fields provider and key are will be added to ProtectedDataType. Therefore, it will be available in ProtectedStringType and ProtectedByteArrayType.

  2. Expressions

    Using standard midpoint library basic. New methods resolveSecretString and resolveSecretBinary were added.

This way XML objects doesn’t have to contain secrets in plain text or encrypted form. Nor tools have to resolve secrets before XML object is being uploaded to midPoint, e.g. midPoint Studio plugin or CI/CD pipes.

Configuration

Configuration of secret providers is located in system configuration object in secretsProviders element. Order of providers doesn’t matter, but it is important to have unique identifiers for each provider. Providers are initialized in order based on their configuration and declared dependencies.

Example of configuration for secret providers
<systemConfiguration xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                     xmlns:o="http://example.com/other">
    ...
    <secretsProviders>
        <docker>
            <identifier>docker-provider</identifier>
        </docker>
        <properties>
            <identifier>properties-provider</identifier>
            <propertiesFile>~/secrets-provider.properties</propertiesFile>
        </properties>
        <environmentVariables>
            <identifier>env-provider</identifier>
            <allowKeyPrefix>MP_</allowKeyPrefix>
        </environmentVariables>
        <file>
            <identifier>file-provider</identifier>
            <parentDirectoryPath>~/secrets</parentDirectoryPath>
        </file>
        <custom>
            <identifier>custom-provider</identifier>
            <className>com.example.MyCustomProvider</className>
            <configuration>
                <o:someConfigurationProperty>value1</someConfigurationProperty>
            </configuration>
        </custom>
    </secretsProviders>
    ...
</systemConfiguration>
Use of such providers
<resource xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3">
    ...
    <connectorConfiguration>
        <configurationProperties>
            ...
            <ldap:password>
                <value>
                    <t:externalData>
                        <t:identifier>docker</t:identifier>
                        <t:key>mysecret</t:key>
                    </t:externalData>
                <!--<t:clearValue>...</t:clearValue>-->
                <!--<t:encryptedData>...</t:encryptedData>-->
                </value>
            </ldap:password>
            ...
        </configurationProperties>
    </connectorConfiguration>
    ...
</resource>

Secret providers

Currently, midPoint supports multiple providers:

  • file - provider for secrets stored in files

  • docker - provider for secrets stored in Docker secrets files

  • properties - provider for secrets stored in properties files

  • environmentVariables - provider for secrets stored in environment variables

  • custom - custom implementation of secrets provider

Generic part of provider configuration

All providers have common part of configuration:

Element Type Description Required

identifier

String

Unique identifier of provider.

Yes

description

String

Optional description.

No

documentation

String

Optional documentation.

No

display

c:DisplayType

Optional display name.

No

cache

xsd:duration

Optional cache duration (TTL). Example: PT1H for 1 hour. If not defined, cache is not used (equivalent of PT0S).

No

allowKeyPrefix

xsd:string

Allowed prefix (multi-value) for the secret keys resolved by this provider. If not specified, all keys are allowed.

E.g. "MYAPP_" - provider will only be able to use environment variables that start with "MYAPP_".

No

File provider

File provider is used to obtain secrets from files. Where the file is located is defined by parentDirectoryPath and

Optional configuration property is charset which defaults to utf-8. It is used to specify the character encoding of the files.

Example of file provider
<file>
    <identifier>file-provider</identifier>
    <parentDirectoryPath>~/secrets</parentDirectoryPath>
</file>

Docker provider

Docker provider just specific implementation of File provider and it’s used to obtain secrets from Docker secrets files (documentation available here). Secrets directory is defined by Docker and it is not configurable. It is always /run/secrets on Linux and C:\ProgramData\Docker\secrets on Windows. Key is the name of the file and value of the key is the content of the file.

Optional configuration property is charset which defaults to utf-8. It is used to specify the character encoding of the files.

Example of Docker provider
<docker>
    <identifier>docker-provider</identifier>
    <cache>PT1H</cache>
</docker>

Properties provider

Secrets provider that reads secrets from properties file defined by propertiesFile element. Optional configuration property is charset which defaults to utf-8. It is used to specify the character encoding of the files.

Example of properties provider
<properties>
    <identifier>properties-provider</identifier>
    <propertiesFile>~/secrets-provider.properties</propertiesFile>
</properties>

Environment variables provider

Custom implementation of secrets provider that reads secrets from environment variables. If useSystemProperties is set to true (default is false), system properties (e.g. -Dkey=value parameters) will be used as well. Search for key first attempts to find it in environment variables and then in system properties.

If prefix is defined, only variables/properties with the given prefix will be used.

Example of environment variables provider
<environmentVariables>
    <identifier>env-provider</identifier>
    <allowKeyPrefix>MP_</allowKeyPrefix>
    <useSystemProperties>true</useSystemProperties>
</environmentVariables>

In this example, only environment variables with prefix MP_ will be used. For example MP_MY_SECRET_VARIABLE=qwe123 has to be referenced in protected string using key MY_SECRET_VARIABLE, prefix will be prepended automatically.

Custom provider

This provider is an advanced experimental feature.

Custom provider allows to plug-in custom implementation of secrets providers available on classpath. Required element className is the fully qualified name of the class implementing com.evolveum.midpoint.xml.ns._public.common.common_3.SecretsProvider interface.

Configuration of custom provider is defined in configuration element. Each element of configuration will be passed to the provider as DOM element, which can be used during initialization of the provider.

Example of custom provider
<custom>
    <identifier>custom-provider</identifier>
    <className>com.example.MyCustomProvider</className>
    <configuration>
        <o:someConfigurationProperty>value1</someConfigurationProperty>
    </configuration>
</custom>

Configuration via GUI

Configuring secret providers via GUI is fully supported in the System section of the menu.

Configuring the current secret via the GUI is fully supported, but visibility is limited.

  • We can see the entire panel in the secrets that are part of the connector configuration, so we can see the configuration for both options, provider and clear value.

  • For the other configurations of the secret data in the basic settings, we only see the configuration for the clear value. In case our secret contains a configuration for the provider, we see a panel for it.

Was this page helpful?
YES NO
Thanks for your feedback