Skip to main content

Default IAM configuration

Learn about the default IAM configuration​

Vault comes with a minimal, default IAM configuration. This default configuration defines a list of roles with access control capabilities and policies suitable for a basic use case involving gathering and using payment details. You can use this configuration as the basis for creating yours, for example, by copying and amending roles to match your needs. Alternatively, some additional configuration examples for some common use cases are provided here. These examples can be copied into a configuration file.

The following users are provided with the default IAM:

  1. Admin – A special built-in user, typically used by the DevOps team or system admin to control the Vault instance. This user has access to all the APIs but, by default, is blocked from accessing data in production. You can control this user's access to data using the PVAULT_SERVICE_ADMIN_MAY_READ_DATA environment variable. You define the user's API key using the PVAULT_SERVICE_ADMIN_API_KEY environment variable.
  2. VaultAdmin – a standard user that has administrative access. Similarly to Admin, this user can access all the APIs. However, unlike Admin, this user can access data operations, and its authentication token is regenerated using the API.
  3. PublicPaymentsTokenizer – a token producer service that only tokenizes sensitive data. For example, tokenizing payment information received from a human user. This role is scoped to the payments collection.
  4. WebApp - a web application that can only pass sensitive data from the Vault to an external service without any access to the data itself. For example, the WebApp user can pass SSN information that was saved with the PublicPaymentsTokenizer to a credit score service without accessing the SSN. The token is automatically detokenized during the http_call and sent to the external credit score service. This role is scoped by default to the payments collection.

Policies​

Policies provide applications and services with access to data. We recommend on using the following schematic naming convention approach to creating new policies. Nonetheless, feel free to create your own conventions.

Sensitivities​

Split properties into data sensitivities groups and use these groups as the lowest granularity for policies. This simplifies the IAM, reduces the number of policies and allows you to focus on fewer considerations. Our recommendation for the sensitivities group:

  • Low – gender, email.mask, and phone_number.mask
  • Medium – date_of_birth, zip_code_us, us_bank_routing, ssn.mask, ban.mask, and cc_number.mask
  • High – email, ssn, phone_number, name, address, us_bank_account_number, ban, cc_holder_name , and cc_expiration_string
  • PCI – cc_number and cc_cvv
  • Meta (all built-in properties) – _*

Note: standard data types aren't covered by any of these policies, as the sensitivity depends on the specific use.

The template​

Define policies names using this template: Policy[Action][Operation][Sensitivity]

  1. Action - Allow or Deny
  2. Operation - the high level operation - [Read|Write|Delete|Search|Tokenize|Detokenize|All]
  3. Sensitivity group - [Meta|Low|Med|High|PCI|All]

The policies​

Policies are defined in your IAM file using this structure:

[policies.PolAllowReadLow]
    operations = [ "<list of operations>" ]
    policy_type = "allow|deny"
    reasons = [ "<list of reasons>" ]
    resources = [  "<list of resources>" ]
  1. The list of operations include: read, write, search, tokenize, detokenize, encrypt, decrypt, hash, stats and invoke. You can also use a wildcard * to include all operations.
  2. The policy is either allow or deny. For an operation to succeed, it must have at least one allow policy and no deny policies.
  3. A complete list of reasons can be found here. You can also use a wildcard * to include reasons.

Examples​

Under this scheme, a policy that allows reading low-sensitivity data types will be named PolicyAllowReadLow and be defined as:

[policies.PolicyAllowReadLow]
    operations = ["read"]
    policy_type = "allow"
    reasons = ["AppFunctionality"]
    resources = ["*/types/GENDER", "*/types/EMAIL.mask", "*/types/PHONE_NUMBER.mask"]

The policy to deny all operations on high-sensitivity data types is named PolicyDenyAllHigh and defined as:

[policies.PolicyDenyAllHigh]
    operations = ["*"]
    policy_type = "deny"
    reasons = ["*"]
    resources = ["*/types/EMAIL", "*/types/STRING", "*/types/SSN", "*/types/PHONE_NUMBER", "*/types/ZIP_CODE_US", "*/types/NAME", "*/types/ADDRESS", "*/types/US_BANK_ACCOUNT_NUMBER", "*/types/BAN", "*/types/CC_HOLDER_NAME", "*/types/CC_EXPIRATION_STRING"]

See the use-cases guide for more examples.

warning

It's strongly recommended that you scope down the permissions provided to each user under the least privileges principle.

On this page