Search
K

Secrets management

To connect identity systems, you will need to include service accounts, administrative credentials, API keys, and other secrets in your configurations. For example, an LDAP Connector will require an admin account and credential in order to lookup users or query for attributes, an Azure AD connector will require a client ID and secret, and your tls configuration may require certificates and keys that are not kept on the local filesystem.
Maverics integrates with various secret management solutions, which store secrets that Orchestrator instances load when starting up. The current integrations include:
If no secret management solution is specified, Maverics will default to loading secrets specified in plain text from the default maverics.yaml configuration file or the base configuration file you've specified (e.g., my-maverics.yaml).
connectors:
- name: ldap
type: ldap
serviceAccountPassword: ldapServiceAccountPassword
serviceAccountUsername: uid=mycorpadmin,ou=Admins,o=MyCorp,c=US
# ...
If Connector configurations are split out and incorporated using include, secrets should be defined in connector-specific files (e.g. myAzureADconnector.yaml)
Each Connector requires different credentials, secrets, and keys. Check the Connectors reference for specifics about what you will need to collect and store in your secret management solution.
To declare a value as a secret in a maverics.yaml config file, wrap the secret with angle brackets:
connectors:
- name: okta
type: okta
apiToken: <oktaAPIToken>
oauthClientID: <oktaOAuthClientID>
oauthClientSecret: <oktaOAuthClientSecret>
Secrets can be used instead of file paths for certificates and keys in the tls section.
tls:
maverics:
certFile: <example.com.crt>
keyFile: <example.com.key>
If connecting to your secret provider involves traversing a network proxy, please see the network proxy documentation.

Hashicorp Vault

Maverics supports third-party products that securely store and manage secrets, credentials, and keys. In this section, we will walk through how to use HashiCorp Vault as your secrets provider.

Deploy HashiCorp Vault

To get started, you will first need to download and install HashiCorp Vault.
After setting up a HashiCorp Vault instance, populate the secrets, and configure authentication for Maverics.
The Maverics Orchestrator currently supports loading secrets from AppRoles or Tokens, AppRoles is recommended.

Loading secrets from HashiCorp Vault using AppRole auth

To enable AppRole auth, specify the role_id and secret_id attributes which are used to fetch a Vault access token. secret_id is not required if secret binding is disabled in your AppRole configuration.
To load secrets from HashiCorp Vault using HTTPS, set the environment variable MAVERICS_SECRET_PROVIDER in the file /etc/maverics/maverics.env, using the following pattern:
MAVERICS_SECRET_PROVIDER='hashivault://<URL OF INSTANCE>/secret/data/maverics?role_id=$ROLE_ID&secret_id=$SECRET_ID'
Maverics will load the necessary secrets from the vault and make them accessible to the runtime.

Loading secrets from HashiCorp Vault using Token auth

To enable token auth, specify the token attribute to specify the auth token used to communicate with Vault.
To load secrets from HashiCorp Vault using HTTPS, set the environment variable MAVERICS_SECRET_PROVIDER in the file /etc/maverics/maverics.env, using the following pattern:
MAVERICS_SECRET_PROVIDER='hashivault://<URL OF INSTANCE>/secret/data/maverics?token=$ACCESS_TOKEN'
Maverics will load the necessary secrets from the vault and make them accessible to the runtime.

Azure Key Vault

To load secrets from Azure Key Vault, set the MAVERICS_SECRET_PROVIDER environment variable in the /etc/maverics/maverics.env file with the credentials attached to your service account application, using the following pattern:
MAVERICS_SECRET_PROVIDER='azurekeyvault://<KEYVAULT NAME>.vault.azure.net?clientID=<APP_CLIENT_ID>&clientSecret=<APP_CLIENT_SECRET>&tenantID=<TENANT_ID>'
In the Orchestrator's configuration file, use the resource name in Key Vault as the placeholder for any secrets.
Azure Key Vault certificates are also supported, but the certificate and key must be PEM encoded, and the file must be in the following format:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----
As of February 2024, Azure does not support loading a PKCS1 .pem key file. If you have a PKCS1 .pem key file, it must be converted to PKCS8 before combining it with the certificate. You can convert PKCS1 to PKCS8 with the following command: openssl pkcs8 -topk8 -inform PEM -outform PEM -in rsa-private-key.pem -out pkcs8-private-key.pem -nocrypt
The file must be imported to the Certificates section, not as a Secret. For more information, see Tutorial: Import a certificate in Azure Key Vault.
In the orchestrator configuration, use the same certificate name from Key Vault for both certFile and keyFile fields. For example:
tls:
maverics:
certFile: <exampleCertPair>
keyFile: <exampleCertPair>
connectors:
- name: azure
type: azure
authType: oauth
oauthClientID: <exampleClientID>
oauthClientSecret: <exampleClientSecret>
# ...

CyberArk Conjur

Maverics Orchestrator can retrieve secrets from CyberArk Conjur (both Conjur Secrets Manager Enterprise and Conjur Open Source) using the Conjur REST API
To load secrets from a Conjur server, set the environment variable MAVERICS_SECRET_PROVIDER in the file /etc/maverics/maverics.env. By default this uses the https scheme. The hostID or login will typically contain special characters (e.g. '/' or '@') which must be URL encoded.
Use the following pattern:
MAVERICS_SECRET_PROVIDER="conjur://<CONJUR_HOST>/<account>/<hostID | login>/?apikey=some-api-key"
Example with a hostID of host/mycompany/myapp:
MAVERICS_SECRET_PROVIDER="conjur://secrets.mydomain.com/myConjurAccount/host%2Fmycompany%2Fmyapp/?apikey=some-api-key"
Example with a login of alice@devops:
MAVERICS_SECRET_PROVIDER="conjur://secrets.mydomain.com/myConjurAccount/alice%40devops/?apikey=some-api-key"
In maverics.yaml use the Conjur resource ID as placeholder for any secrets or passwords. Use the conjur CLI or the List Resources API to find the specific variable ID. For example:
connectors:
- name: azure
type: azure
oauthClientID: <myConjurAccount:variable:apps/clientID>
oauthClientSecret: <myConjurAccount:variable:mycompany/secret>
# ...

Delinea Secret Server

Maverics Orchestrator can retrieve secrets from the Delinea Secret Server using their REST API. All the secrets must be co-located in a single folder which must be specified in the connection URL.
To load secrets from a Delinea server, set the environment variable MAVERICS_SECRET_PROVIDER in the file /etc/maverics/maverics.env.
Use the following pattern:
MAVERICS_SECRET_PROVIDER="delinea://<DELINEA_HOST>?username=yourUser&password=yourPassword&folder=\\some\\folder"
Example with a DELINEA_HOST of yourAccount.secretservercloud.com:
MAVERICS_SECRET_PROVIDER="delinea://yourAccount.secretservercloud.com?username=yourUser&password=yourPassword&folder=\\maverics"
To support password or folders with special characters they should be URI encoded, for example using a user with password '()Pass1234&^%" the connection string would look like:
MAVERICS_SECRET_PROVIDER="delinea://yourAccount.secretservercloud.com?username=yourUser&password=%27%28%29Pass1234%26%5E%25%22&folder=\\maverics"
In maverics.yaml use the Delinea secret's slug field and its path like <secretName.slug>, as placeholder for fields you wish to populate from the secret server. Check the secret's template to find the value of the field's slug. See an example configuration below:
connectors:
- name: azure
type: azure
oidcWellKnownURL: <secretName.wellKnown>
oauthClientID: <secretName.client-id>
oauthClientSecret: <secretName.client-secret>
# ...

Delinea setup for Secret Provider user

The user used to get the secrets needs to have the following permissions:
  • Access to the folder where the secrets are stored
  • View Secret permission
  • Administer Secret Templates permission
For correct setup of the Maverics Secrets Provider user, consider doing the following:
  • Create maverics-api-users group
  • Edit the folder permissions to allow access from the maverics-api-users group
  • Create a maverics-secret-provider role with the following permissions:
    • View Secret
    • Administer Secret Templates
  • Assign the maverics-secret-provider role to the maverics-api-users group
  • Create a maverics-secrets-user user and assign them to the maverics-api-users group

Secrets File

Strata strongly recommends using a vault as your secrets provider, even just for evaluation or test instances. The file-based options are provided for convenience only.
To load secrets from a file, set the environment variable MAVERICS_SECRET_PROVIDER in the file /etc/maverics/maverics.env, using the following pattern:
MAVERICS_SECRET_PROVIDER=secretfile:////etc/maverics/secrets.yaml
To load secrets from a file using the CLI flag, use the following pattern:
maverics -secretProvider secretfile:////etc/maverics/secrets.yaml
The file contents can be filled with any number of secrets:
secrets:
oktaAPIToken: aReallyGoodToken
oktaOAuthClientID: aReallyUniqueID
oktaOAuthClientSecret: aReallyGoodSecret
samlSigningCert: |+ # Multi-line values require |+.
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
saml-signing-key: |+
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----