Dynamic Providers and Accounts Configuration

Dynamic Providers are privileged identities which 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 which 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 will in turn delete these principals from the cloud provider.

Important Notes

  • Because Dynamic Account functions interact with cloud environments, bulk operations will often have performance directly tied 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.

Dynamic Account Example

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 succcess code. This provider has the DSS uri:

-`/dynamic/AzureProvider`

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

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

Managing 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 CLI Commands

The ssrun commandline 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 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 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 will be returned for the dynamic account only upon this initial creation. Further reads will return only identifiers and insensitive details.

Dynamic Account Definition 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",
        "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 may 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 in to 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: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 may 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",
   "options": {
     "AccessKeyId": "<value>",
     "SecretAccessKey": "<value>",
     "Region:" "us-east-2"
  }
}
POST /secretssafe/api/v1/dynamic/AwsDynamicProvider
{
   "type": "AwsPolicy",
   "name": "AwsExampleDynamicAccountDefinition",
   "enabled": true,
   "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",
   "options": {
     "ClientId": "<value>",
     "ClientSecret": "<value>",
     "TenantId": "<value>",
     "SubscriptionId": "<value>"
  }
}
POST /secretssafe/api/v1/dynamic/{provider == AzureDynamicProvider}
{
   "type": "AzureRole",
   "name": "AzureExampleDynamicAccountDefinition",
   "enabled": true,
   "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.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 may 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",
   "options": {
      "ProjectId": "<value>",
      "GcpCredentialsJson": "<value>"
  }
}
{
    "type": "GcpRole",
    "name": "GcpAccountDefinition",
    "enabled": true,
    "options": {
       "Roles": ["roles/apigee.analyticsEditor", "roles/iam.serviceAccountCreator"]
    }
}
POST /secretssafe/api/v1/dynamic/GcpDynamicProvider/GcpAccountDefinition