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:

• HashiCorp Vault
• Azure Key Vault
• CyberArk Conjur
• CyberArk CCP
• Delinea Secret Server
• YAML file (e.g., secrets.yaml)

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>

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-----

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>
     # ...

CyberArk CCP

Maverics Orchestrator can retrieve secrets from CyberArk CCP.

CyberArk CCP is using certificate authentication method, so you need to provide the path to the root CA certificate, client certificate, and client key. To load secrets from the CCP, set the environment variable MAVERICS_SECRET_PROVIDER in the file /etc/maverics/maverics.env

MAVERICS_SECRET_PROVIDER="cyberarkccp://secrets.mydomain.com?appID=some-app-id&safe=some-safe&caFile=rootCA.crt&certFile=client.crt&keyFile=client.pem""

Optionally, you can specify folder parameter as well.

MAVERICS_SECRET_PROVIDER="cyberarkccp://secrets.mydomain.com?appID=some-app-id&folder=my-folder&safe=some-safe&caFile=rootCA.crt&certFile=client.crt&keyFile=client.pem"

For more detailed parameters description, please refer to the CyberArk CCP documentation.

keyFile=%2Fetc%2Fmy%20certs%2Fthe%20key.pem

Loading certificates from the Windows Store

If you wish to load a certificate from the Windows Store, you can use a thumbprint or subject of a desired auth certificate or root CA. For an authentication cert, use winCertThumbprint or winCertSubject parameters. For root CA, use winRootCAThumbprint or winRootCASubject parameters. If you are using root CA thumbprint and do not provide the subject or file, the default system certificates will be loaded.

Example with thumbprint:

MAVERICS_SECRET_PROVIDER="cyberarkccp://secrets.mydomain.com?appID=some-app-id&safe=some-safe&winCertThumbprint=1234567890ABCDEF1234567890ABCDEF12345678&winRootCAThumbprint=1234567890ABCDEF1234567890ABCDEF12345678"

With subject:

MAVERICS_SECRET_PROVIDER="cyberarkccp://secrets.mydomain.com?appID=some-app-id&safe=some-safe&winCertSubject=cert.example.com&winRootCASubject=ca.example.com"

Using secrets in configuration

To declare a value as a secret in a maverics.yaml config file, wrap the secret (object name) with angle brackets:

connectors:
  - name: okta
    type: okta
    apiToken: <oktaAPIToken>
    oauthClientID: <oktaOAuthClientID>
    oauthClientSecret: <oktaOAuthClientSecret>

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

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-----