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
• AWS Secrets Manager
• 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.

Loading secrets from a specific namespace in HashiCorp Vault

For secrets stored in namespaces, specify the namespace attribute as a query parameter of the HashiCorp Vault address. Note that at the time of this writing, namespace is only supported for the Vault Enterprise edition.

MAVERICS_SECRET_PROVIDER='hashivault://<URL OF INSTANCE>/secret/data/maverics?role_id=$ROLE_ID&secret_id=$SECRET_ID&namespace=admin/my-namespace'

AWS Secrets Manager

Maverics can integrate with AWS to inject secrets stored in AWS Secrets Manager into Maverics user flows to protect app resources. Maverics can also decrypt KMS-encrypted secrets stored in Secrets Manager.

Prerequisites

In order to use Secrets Manager with Maverics, you will need the following:

• A new IAM user
• Sufficient permissions for your new IAM user as defined in AWS IAM Configuration below.
• AWS AccessKey, Secret Access Key, and Region for the IAM user associated with Secrets Manager
• Maverics secrets in Secrets Manager (plain text or key/value)

See the documentation linked in each entry for more details.

Update your Maverics configuration with AWS secrets

The AWS Secrets Manager supports plain text and key/value JSON structured secrets. You must revise your Maverics configuration with references to secrets in AWS. For more information, see Create and manage secrets with AWS Secrets Manager.

Plain text secrets

Use the secret ID or secret name as placeholder for any multi-line secrets or passwords.

apps:
  - name: exampleSAMLApp
    type: saml
    audience: https://app.enterprise.com
    consumerServiceURL: https://app.enterprise.com/acs
    requestVerification:
      certificate: <dev/exampleSAMLApp/signingCertificate>
     # ...

Key/value JSON secrets

Use the format of <secret ID:secret key> as placeholder for any secrets or passwords.

connectors:
   - name: azure
     type: azure
     oauthClientID: <dev/app100:clientID>
     oauthClientSecret: <dev/app100:clientSecret>
     # ...

If a secret key is provided, the value of the key from the JSON object is returned. If only the secret ID is provided, the entire JSON secret is returned.

AWS IAM Configuration

The Secrets Manager policy settings should allow only what Maverics needs in order to fetch secret value.

See AWS documentation for more: https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_examples.html

AWS IAM Resource Policy

The following example is a resource-based policy that you can attach to a secret. This example is useful when you want to grant access to a single secret to multiple users or roles.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::AccountId:role/EC2RoleToAccessSecrets"
      },
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "*"
    }
  ]
}

AWS IAM User Permissions Policy

Create access keys for an AWS IAM user with tightly scoped permissions. The following JSON shows an appropriate policy for an IAM user with access to the minimal permissions required for secret retrieval:

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "secretsmanager:GetSecretValue"
    ],
    "Resource": "*"
  }
}

AWS Decrypt customer managed keys policy

If a secret is encrypted using a customer managed key, you must grant access to decrypt the secret by attaching the following policy to an identity.

1. Attach the policy to the IAM identity either by adding/editing permissions, or by creating an inline policy.
2. Set the resource for the kms:Decrypt action as the KMSkey ARN.

For complete information, see Attach a permissions policy to an identity.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "SecretARN"
    },
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "KMSKeyARN"
    }
  ]
}

Maverics Configuration

To load secrets from AWS Secrets Manager, set the MAVERICS_SECRET_PROVIDER environment variable using the following pattern:

MAVERICS_SECRET_PROVIDER='awssecretsmanager://amazonaws.com'

To override the AWS environment configuration, accessKeyID, secretAccessKey and region can be specified on the connection string. Ensure the fields are properly URL encoded.

MAVERICS_SECRET_PROVIDER='awssecretsmanager://amazonaws.com?accessKeyID=aws-access-key-id&secretAccessKey=aws-secret-access-key&region=us-east-2'

./maverics_darwin_amd64 -secretProvider "awssecretsmanager://amazonaws.com" -config maverics.json

If referencing environment variables:

source ./maverics.env && ./maverics_darwin_amd64

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 MAVERICS_SECRET_PROVIDER environment variable, using the following pattern:

MAVERICS_SECRET_PROVIDER="conjur://"

By default, Maverics will use the Cyberark Conjur environment configuration. For example, Conjur environment variables CONJUR_* or CONJURRC file.

To override the Cyberark Conjur environment configuration, account, hostID or login, and apikey can be specified on the connection string. Ensure the fields are properly URL encoded.

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"

Permissions

Ensure that the API Key or other method of authentication has the minimal read permissions to access the secrets referenced in the configuration.

Using secrets in configuration

In maverics.yaml use the Conjur secret name as placeholder for any secrets or passwords. For example:

connectors:
   - name: azure
     type: azure
     oauthClientID: <apps/clientID>
     oauthClientSecret: <mycompany/secret>
     # ...

The variable identifiers can also be referenced in the following format:

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