IAM configuration file

Learn about the IAM configuration file structure

Identity and access management users, roles, and policies are defined using a TOML file loaded using the Set IAM configuration REST API endpoint or CLI command.

The TOML file must contain three sections, in any order.

Users

Users are defined with the [users] keyword like this:

[users.<name>]
    role = "<role_name>"

Where <role_name> is any valid string.

Roles

Users are defined with the [roles] keyword like this:

[roles.<role_name>]
    policies = [<policies-list>]
    capabilities = [<capabilities-list>]

Where:

• <role_name> is any valid string.
• <policies-list> is a comma-separated list of policies or "*" to indicate that all policies are included.
• <capabilities-list> is a comma-separated list of capabilities or "*" to indicate that all capabilities are included. These are the capabilities by scope:

Scope	Prefix	Methods	Capability
Data	/api/pvlt/1.0/data	GET	"CapDataReader"
		POST	"CapDataWriter" or "CapDataCreator"
		PATCH	"CapDataWriter" or "CapDataUpdater"
		DELETE	"CapDataWriter" or "CapDataDeleter"
Data query	/api/pvlt/1.0/data/collections/*/query/objects	POST	"CapDataSearcher"
Objects	/api/pvlt/1.0/data/collections/*/objects/*	GET	"CapOjectsReader"
		POST	"CapObjectsWriter" or "CapObjectsCreator"
		PATCH	"CapObjectsWriter" or "CapObjectsUpdater"
		DELETE	"CapObjectsWriter" or "CapObjectsDeleter"``
Objects lister Note: This Capability also allows reading objects data by ID	/api/pvlt/1.0/data/collections/*/objects	GET	"CapObjectsLister"
Tokens	/api/pvlt/1.0/data/collections	GET	"CapTokensDetokenizer"
		POST, PATCH, and DELETE	"CapTokensWriter"
Tokens query	/api/pvlt/1.0/data/collections/*/query/tokens	POST	"CapTokensReader"
Tokens rotate	/api/pvlt/1.0/data/collections/*/rotate/tokens	POST	"CapTokensWriter"
Transaction ID	/api/pvlt/1.0/data/collections/*/transaction_id	GET	"CapTransactionIdReader"
Encrypt	/api/pvlt/1.0/data/collections/*/encrypt/*	POST	"CapCryptoEncrypter"
		PATCH	"CapCryptoDecrypter" and "CapCryptoEncrypter"
Decrypt	/api/pvlt/1.0/data/collections/*/decrypt/*	POST	"CapCryptoDecrypter"
Hash	/api/pvlt/1.0/data/collections/*/hash/*	POST	"CapCryptoHasher"
Action	/api/pvlt/1.0/ctl/actions	GET	"CapActionsReader"
Action invoker	/api/pvlt/1.0/data/actions	POST	"CapActionsInvoker"
Identity and access management	/api/pvlt/1.0/ctl/iam	GET	"CapIAMReader"
		POST	"CapIAMWriter"
Bundles	/api/pvlt/1.0/ctl/bundles	GET	"CapCodeReader"
		POST, PATCH, and DELETE	"CapCodeWriter"
Data types	/api/pvlt/1.0/ctl/types	GET	"CapTypesReader"
		POST, PATCH, and DELETE	"CapTypesWriter"
Schema	/api/pvlt/1.0/schema	GET	"CapCollectionsReader"
		POST, PUSH, PATCH, and DELETE	"CapCollectionsWriter"
Garbage collection (pruning)	/api/pvlt/1.0/system/admin/lifecycle/gc	POST	"CapSystemGCRunner"
Configuration variables	/api/pvlt/1.0/system/confvar	GET	"CapConfvarReader"
		POST, PATCH, and DELETE	"CapConfvarWriter"
KMS	/api/pvlt/1.0/system/info/kms	GET	"CapKMSReader"
KMS rotate	/api/pvlt/1.0/system/admin/keys/rotate	POST	"CapKMSWriter"
Export key	/api/pvlt/1.0/system/admin/export_key	GET	"CapExportKeyReader"
Version	/api/pvlt/1.0/system/info/version	All	"CapInfoReader"
System information	/api/pvlt/1.0/system/info	GET	"CapInfoReader"
Cluster information	/api/pvlt/1.0/ctl/info/cluster	GET	"CapClusterInfoReader"
Error	/api/pvlt/1.0/system/debug/error/trigger	POST	"CapErrorWriter"
Health	/api/pvlt/1.0/data/info/health	All	Not required
	/api/pvlt/1.0/ctl/info/health	All	Not required

note

The roles ConsoleAdmin and ConsoleReadOnly are used by the Piiano SaaS.

Policies

Policies are defined with the [policies] keyword like this:

[policies.<policy-name>]
    policy_type = "allow"|"deny"
    operations = [<operations-list>]
    reasons = [<reasons-list>]
    resources = [<resources-list>]

Where:

• operations-list is a comma-separated list of one or more of these values or "*" to indicate that all operations are included:

  • "read"
  • "write"
  • "delete"
  • "search"
  • "tokenize"
  • "detokenize"
  • "encrypt"
  • "decrypt"
  • "hash"
  • "stats"

• reasons-list is a comma-separated list of one or more of these values or "*" to indicate that all reasons are included:

  • AppFunctionality
  • Analytics
  • Notifications
  • Marketing
  • ThirdPartyMarketing
  • FraudPreventionSecurityAndCompliance
  • AccountManagement
  • Maintenance
  • DataSubjectRequest
  • Other, used when an ad-hoc reason is specified.

• resources-list is a comma-separated list of one or more resources:

  • builtin data types specified as <collection–name>/types/<type-name>, <type-name> must be in uppercase.
  • properties specified as <collection–name>/properties/<property–name>.
  • transformations specified as <collection–name>/transformations/<transformation–name>.
  • tokens specified as <collection–name>/tokens.
  • archived items specified as <collection–name>/archived/[properties|tokens][/<property–name>].

  <collection–name>, <type-name>, <property–name>, or |<transformation–name>] can be specified as "*" to indicate that all collections, data types, properties, or transformations are included.

  For example:

  • "buyers/types/EMAIL" refers to the all the properties in the buyers collection based on the EMAIL data type.
  • "employees/properties/email" refers to the email property of the employees collection.
  • "*/properties/email" refers to the email property in any collection.
  • "customers/transformations/ssn.mask" refers to the mask transformation of the ssn property of the customers collection.
  • "*/tokens" refers to tokens in any collection.
  • "customers/archived/*" refers to any property of archived objects in the customers collection.

Example

This example shows the specification of:

• A CollectionsManager user.
• A CollectionsReaderWriter role. The CollectionsReaderWriter role has the capabilities to enable it to maintain the schema of collections.
• Two policies allowing read and write for all properties and transformations for any reason.

[users]

    [users.CollectionsManager]
        role = "CollectionsReaderWriter"

[roles]

    [roles.CollectionsReaderWriter]
        capabilities = ["CapCollectionsReader", "CapCollectionsWriter"]
        policies = ["PolReadAll","PolWriteAll"]

[policies]

    [policies.PolReadAll]
        policy_type = "allow"
        operations = ["read"]
        reasons = ["*"]
        resources = ["*"]
    
    [policies.PolWriteAll]
        policy_type = "allow"
        operations = ["write"]
        reasons = ["*"]
        resources = ["*"]