Dynamic Providers and Accounts Configuration

Dynamic Providers are privileged identities that allow DevOps Secrets Safe to authenticate into cloud environments and create Dynamic Accounts.

There are no Dynamic Providers enabled by default. Dynamic Providers may be configured for Amazon Web Services (AWS), Google Cloud Platform (GCP), or Microsoft Azure.

Once a Dynamic Provider is configured, Dynamic Account Definitions must be created to define the privileges that will be delegated to future Dynamic Accounts.

Once a Dynamic Provider and Dynamic Account Definition have been created, new Dynamic Accounts may be generated, thereby creating new principals in the cloud environment. Deleting these Dynamic Accounts in Secrets Safe causes deletion of the associated principals from the cloud provider.

Important Notes

  • Because Dynamic Account functions interact with cloud environments, bulk operations' performance is often tied directly to the cloud environment's ability to complete operations.
  • Because Dynamic Accounts are backed by actual cloud principals, the objects DevOps Secrets Safe creates count toward quotas in the cloud environment.
  • Because Dynamic Providers and Account Definitions depend on cloud objects such as roles and access keys, do not modify these objects in the cloud environment without making corresponding updates to Secrets Safe entities.
  • The security boundary of a created Dynamic Account Principal within the cloud provider is governed only by what is specified in the Account Definition and through any manual actions in the cloud provider. No additional security measures are imposed on the cloud principal by Secrets Safe to prevent privilege escalation.

Create a Dynamic Account With a Lifetime Duration

Posting the following Dynamic Provider configuration to /dynamic creates a dynamic provider of the type Azure and with the name AzureProvider. On creation DevOps Secrets Safe reaches out to Azure and ensures the credentials provided are valid before returning a success code. This provider has the DSS URI:

/dynamic/AzureProvider

{
   "Type": "Azure",
   "Name": "AzureProvider",
   "CredentialRotationEnabled": false,
   "Options": {
      "ClientId": "<client_id>",
      "ClientSecret": "<client_secret>",
      "TenantId": "<tenant_id>",
      "SubscriptionId": "<subscription_id>"
   }
}
{		
   "type": "AzureRole",
   "name": "VMContributor",
   "MaxExpiryDurationMinutes": 60
   "options": {
       "RoleAssignments": [
        {
          "Scope": "/subscriptions/<subscription_id>/",
          "Role": "Contributor"
     }
    ]
 }
}

The specification of MaxExpiryDurationMinutes as 60 means that Dynamic Accounts created from this definition have a maximum lifetime duration of 60 minutes. The expiry duration for a Dynamic Account instance is specified as part of the account creation request that happens in the next step.

Now Dynamic Accounts can be created using this provider/account definition combination. Making a POST to /dynamic/AzureProvider/VMContributor does the following:

  • Authenticates using the credentials in the AzureProvider dynamic provider
  • Creates a Service Principal in Azure and creates a role assignment using the Scope and Role found in the VMContributor account definition
  • Creates a DevOps Secrets Safe dynamic account found at /dynamic/AzureProvider/VMContributor/<account_name>
  • Returns the credentials needed to log into Azure using the newly created Service Principal
  • Schedule the removal of the created account to occur after its expiry duration elapses. The timestamp for expiry is returned in the creation response.

Manage Dynamic Providers

Dynamic Providers can be configured using the CLI or the API. Management permissions for Dynamic Provider configurations are CRUD operations within the resource path /dynamic.

Once configured, the resource URI for a Dynamic Provider is /principal/<providerName>. Subsequent posts to that route allow the creation of an Account Definition.

Dynamic Provider Credential Rotation

The credentials supplied for a Dynamic Provider can be managed and regularly rotated by DSS. Dynamic Providers opt in to credential rotation by setting the top-level field CredentialRotationEnabled to true.

A credential is rotated when its value is changed. The original credential becomes invalid after a rotation takes place.

For Dynamic Providers that enable credential rotation, the following actions are taken:

  • The credentials are rotated immediately at provider creation or update time in DSS.
  • Regular rotation of the credential is scheduled to take place every 24 hours following the initial rotation, as long as the provider remains configured in DSS.

Deleting the provider from DSS also removes the scheduled rotation behavior for the provider's credentials.

Once a provider is configured, its credentials cannot be retrieved via the DSS API. This means that the credentials for the provider that are known by the DSS operator become invalid immediately after configuring a provider with credential rotation enabled, and the new valid credentials cannot be retrieved.

Credential Rotation Effectiveness Delay

For remote cloud systems where credentials are being rotated, there may be a time interval during which both original (pre-rotation) and new (rotated) credentials remain valid. This relates to propagation delays for changes in cloud provider IAM systems and is not under the control of DSS.

Dynamic Provider CLI Commands

The ssrun command line utility may be used to list, inspect, create, update, or delete Dynamic Providers.

  • ssrun dynamic provider get: Returns a JSON array of all Dynamic Provider configurations. Adding the -p flag and the name of a provider returns only that specific provider.
$ ssrun dynamic provider get
{
    "Uri": "/dynamic",
    "Providers": [
        { 
          "Uri": "/dynamic/GcpGet1",
          "Name": "GcpGet1",
          "Type": "Gcp"
        },  
        {
          "Uri": "/dynamic/AzureGet1",
          "Name": "AzureGet1",
          "Type": "Azure"
        }
}
  • ssrun dynamic provider create -f myConfig.txt: Creates a Dynamic Provider described in the config file myConfig.txt.
  • ssrun dynamic provider update -f myConfig.txt -p <providerName> : Updates the Dynamic Provider named <providerName> with the contents of the configuration file myConfig.txt. The name and type fields for a provider are static and cannot be changed by an update operation. All other fields can be modified.
  • ssrun dynamic provider delete -p <providerName>: Deletes the Dynamic Provider configuration named <providerName>. Upon deletion, the named provider is removed along with all nested account definitions and Dynamic Accounts.

Manage Dynamic Account Definitions

Dynamic Account definitions are managed under the CRUD permissions within the resource path for a Dynamic Provider /dynamic/<providerName>.

Once configured, the resource URI for a Dynamic Account definition is /principal/<providerName>/<accountDefinitionName>. Subsequent posts to that route allow the creation of Dynamic Accounts.

Dynamic Account Definition Maximum Duration Configuration

Dynamic Account definitions specify the maximum lifetime duration for Dynamic Accounts created using the definition.

The top-level field MaxExpiryDurationMinutes specifies a number of minutes that defines the maximum lifetime duration for descendant Dynamic Accounts.

A setting of 0 implies no limit. No maximum lifetime duration is enforced for Dynamic Accounts created from a definition having 0 max expiry. The expiry duration for a Dynamic Account is specified in its creation request.

Any nonzero, positive value specified for this field becomes the maximum lifetime duration for descendant Dynamic Accounts.

For more information about the expiry duration of a Dynamic Account, please see Dynamic Account Creation Options.

Dynamic Account Definition CLI Commands

The ssrun command line utility may be used to list, inspect, create, update, or delete Dynamic Account definitions.

  • ssrun dynamic account-definition get -p <providerName>: Returns a JSON array of all Dynamic Account definitions. The -p flag followed by the name of a provider is mandatory. The -a flag followed by an Account Definition name may be specified to return only that Account Definition.

$ ssrun dynamic account-definition get -p <providerName> { "Uri": "/dynamic/AwsTextures1", "Name": "AwsNegative1", "Type": "AWS", "Account Definitions:": [ { "Uri": "/dynamic/AwsTextures1/Slippery" }, { "Uri": "/dynamic/AwsTextures1/Bumpy" } ] }

  • ssrun dynamic account-definition create -p <providerName> -f myConfig.txt: Creates a Dynamic Account Definition described in the config file myConfig.txt nested under the Dynamic Provider <providerName>.
  • ssrun dynamic account-definition update -f myConfig.txt -p <providerName> -a <accountDefinitionName>: Updates the Dynamic Account Definition named <accountDefinitionName> with the contents of the configuration file myConfig.txt. The name and type fields for an Account Definition are static and cannot be changed by an update operation. All other fields are eligible for modification. Any updates to an Account Definition apply only to new Dynamic Accounts and do not affect existing instances.
  • ssrun dynamic account-definition delete -n <providerName> -a <accountDefinitionName>: Deletes the Dynamic Account definition named <accountDefinitionName> nested under provider <providerName>. Upon deletion, the named Account Definition is removed along with all nested Dynamic Accounts.

Manage Dynamic Accounts

Dynamic Accounts are managed under the Create, Read, and Delete permissions within the resource path for a Dynamic Account Definition: /dynamic/<providerName>/<accountDefinitionName>.

Once created, the resource URI for a Dynamic Account is principal/<providerName>/<accountDefinitionName>/<accountName>. The credentials and any other sensitive data is returned for the Dynamic Account only upon this initial creation. Further reads return only identifiers and insensitive details.

Dynamic Account Creation Options

The Dynamic Account creation request allows specification of options for the created account. The available options are:

  • Name: Specifies the name to use for the account in the cloud provider and in DSS. If not specified, a name is auto-generated from a combination of the provider, account definition, and a pseudo-random string suffix.
  • ExpiryDurationMinutes: Specifies the lifetime duration of this account in minutes before it expires. When an account expires, DSS takes action to remove it from the cloud provider and from DSS. The maximum expiry duration is specified on the Dynamic Account Definition referenced for account creation. Setting this to 0 requests an account that never expires, and is only allowed if the Account Definition also specifies 0 as the maximum expiry duration.

The following sample request body for a Dynamic Account creation request shows the available options for a new Dynamic Account, with name override specified as RobotAccount1 and expiry duration specified as 60 minutes:

{
	"name": "RobotAccount1",
	"expiryDurationMinutes": 60
}

Dynamic Account Creation Effectiveness Delay

For remote cloud systems where accounts are being created by DSS, there may be a time interval after creation appears successful to DSS but before the credentials for the new account become valid in the cloud provider's API. This relates to propagation delays for changes in cloud provider IAM systems and is not under the control of DSS.

For Google Cloud Platform (GCP), this delay could be up to 7 minutes.

For AWS and Azure, this delay could also be on the order of minutes as the cloud service does not immediately reach its eventually consistent state in which the account exists. In many cases, the change appears almost immediately, though such performance is not guaranteed by the cloud systems.

For more information on Google's Cloud Platform, please see Google's Frequently Asked Questions .

Dynamic Account CLI Commands

The ssrun command line utility may be used to list, inspect, create, or delete Dynamic Accounts.

  • ssrun dynamic account get -p <providerName> -a <accountDefinitionName>: Returns a JSON array of all Dynamic Accounts, the -p flag followed by the name of a provider and the -a flag followed by the name of an Account Definition are mandatory. The -n flag followed by an account name may be specified to return only that account.
$ ssrun dynamic account get -p AzureCloud3 -a Manager
{
        "Uri": "/dynamic/AzureCloud3/Manager",
        "Name": "Manager",
        "Type": "AzureRole",
        "MaxExpiryDurationMinutes": 60,
		"Accounts:": [
        {
            "Uri":"/dynamic/AzureCloud3/Manager/e9d8c348-e709-43b2-980d-d4d533de7975"
        },
        {
            "Uri":"/dynamic/AzureCloud3/Manager/e9b7b893-fb73-4355-9df0-049e2826eee9"
        }
     ]
}
  • ssrun dynamic account create -p <providerName> -a <accountDefinitionName>: Creates a Dynamic Account nested under the Dynamic Account Definition <accountDefinitionName> within the provider <providerName>. The name automatically takes on the form DSS-<providerFirst8Chars>-<accountDefFirst8Chars>-<randomString> unless it is overridden in a config file which is passed in using the -f flag.
  • ssrun dynamic account delete -p <providerName> -a <accountDefinitionName> -n <accountName>: Deletes the Dynamic Account named <accountName> nested under Account Definition <accountDefinitionName> and under provider <providerName>. Upon deletion, the cloud principal backing this DevOps Secrets Safe Dynamic Account object is deleted as well. If any errors occur in the cloud interaction which prevent the cloud principal from being deleted, the call fails with an explanation and the account takes on the OutOfSync status. A subsequent delete call with the purge local resourcesflag may then be executed if it is desirable to delete the DevOps Secrets Safe object representation without deleting the cloud object.

Supported Dynamic Provider Types

Dynamic Providers can be configured for Amazon Web Services (AWS), Google Cloud Platform (GCP), or Microsoft Azure. Each of these providers must be backed by a cloud principal in their respective cloud environments. These principals must have at least the minimum permissions necessary to perform the actions required to create DevOps Secrets Safe Dynamic Accounts.

Upon creation of a provider, basic checks are performed to ensure the principal can log into the cloud environment and inspect permissions within. If this interaction fails, the creation of the provider also fails. Similarly, when Account Definitions are later created, it will be verified that the provider principal is able to view the described privileges before the Account Definition creation succeeds.

AWS

AWS Provider Principal Requirements

In order to create a Dynamic Provider for AWS, a user with programmatic access is required. The Access Key ID and the Secret Key must be posted to DevOps Secrets Safe to create the provider. The backing principal must have one or more policies which grant them the following permissions:

  • iam:ListPolicies
  • iam:ListAccessKeys
  • iam:ListGroupsForUser
  • iam:ListUsers
  • iam:ListAttachedUserPolicies
  • iam:CreateAccessKey
  • iam:CreateUser
  • iam:DeleteAccessKey
  • iam:DeleteUser
  • iam:GetUser
  • iam:RemoveUserFromGroup
  • iam:AttachUserPolicy
  • iam:DetachUserPolicy

If a quicker and less restrictive policy is desired rather than a least privilege policy, the policy arn:aws:iam::aws:policy/AdministratorAccess can be used.

AWS Sample Scenarios

The following are examples of creating a dynamic provider, account definition, and account instance in AWS:

POST /secretssafe/api/v1/dynamic
{
   "type": "AWS",
   "name": "AwsDynamicProvider",
   "CredentialRotationEnabled": false,		
   "options": {
     "AccessKeyId": "<value>",
     "SecretAccessKey": "<value>",
     "Region:" "us-east-2"
  }
}
POST /secretssafe/api/v1/dynamic/AwsDynamicProvider
{
   "type": "AwsPolicy",
   "name": "AwsExampleDynamicAccountDefinition",
   "MaxExpiryDurationMinutes": 60,
   "options": {
    "PolicyARNs":[
	"arn:aws:iam::aws:policy/AlexaForBusinessDeviceSetup"
    ]
   }
  }
POST
/secretssafe/api/v1/dynamic/AwsDynamicProvider/AwsExampleDynamicAccountDefinition

Azure

Azure Provider Principal Requirements

In order to create a Dynamic Provider for Azure, a service principal is required. The Client ID, Client Secret, Tenant ID, and Subscription ID must be posted to DevOps Secrets Safe to create the provider. The service principal must have the Owner role assigned through Azure RBAC and must have the API Permission Azure Active Directory Graph > Application.ReadWrite.OwnedBy assigned in AAD.

The legacy Azure Active Directory Graph must be used instead of the newer Microsoft Graph until the Application.ReadWrite.OwnedBy issue described at https://github.com/microsoftgraph/microsoft-graph-docs/issues/7911 is resolved.

Azure Sample Scenarios

The following are examples of creating a Dynamic Provider, Account Definition, and account instance in Azure.

POST /secretssafe/api/v1/dynamic
{
   "type": "Azure",
   "name": "AzureDynamicProvider",
   "CredentialRotationEnabled": false,		
   "options": {
     "ClientId": "<value>",
     "ClientSecret": "<value>",
     "TenantId": "<value>",
     "SubscriptionId": "<value>"
  }
}
POST /secretssafe/api/v1/dynamic/{provider == AzureDynamicProvider}
{
   "type": "AzureRole",
   "name": "AzureExampleDynamicAccountDefinition",
   "MaxExpiryDurationMinutes": 60,
   "options": {
     "RoleAssignments": [
     {	
          "Scope": "/subscriptions/<subscription_id>/"
          "Role": "Contributor”
     }
    ]
   }
}
POST
/secretssafe/api/v1/dynamic/AzureDynamicProvider/AzureExampleDynamicAccountDefinition

GCP

GCP Provider Principal Requirements

In order to create a Dynamic Provider for GCP, a service account is required. The credentials JSON and the projectID must be posted to DevOps Secrets Safe to create the provider. The service account must have IAM policy bindings to one or more roles which grant them the following permissions:

  • iam.roles.get
  • iam.roles.list
  • iam.serviceAccountKeys.create
  • iam.serviceAccountKeys.delete
  • iam.serviceAccountKeys.get
  • iam.serviceAccountKeys.list
  • iam.serviceAccounts.create
  • iam.serviceAccounts.delete
  • iam.serviceAccounts.get
  • iam.serviceAccounts.list
  • iam.serviceAccounts.update
  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy

If a quicker and less restrictive role is desired rather than a least privilege role, then the Owner role can be used.

GCP Sample Scenarios

The following is an example of creating a Dynamic Provider in GCP:

POST /secretssafe/api/v1/dynamic
{
   "type": "GCP",
   "name": "GcpDynamicProvider",
   "CredentialRotationEnabled": false,
   "options": {
      "ProjectId": "<value>",
      "GcpCredentialsJson": "<value>"
  }
}

The value of GcpCredentialsJson should be valid credentials in the Google Credentials File format. Evaluation of these credentials and their form is done solely by GCP.

POST /secretssafe/api/v1/dynamic/GcpDynamicProvider
{
    "type": "GcpRole",
    "name": "GcpAccountDefinition",
    "MaxExpiryDurationMinutes": 60,
    "options": {
       "Roles": ["roles/apigee.analyticsEditor", "roles/iam.serviceAccountCreator"]
    }
}
POST /secretssafe/api/v1/dynamic/GcpDynamicProvider/GcpAccountDefinition