IAM configuration file

Learn about the IAM configuration file structure

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

The TOML file must contain users, roles, and policies tables, and can include an idps table. These tables can be specified in any order. See JWT configuration in the IAM file for reference information on the idps tables.

Users

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

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

Where <role_name> is any valid string.

Roles

Users are defined with the [roles] heading 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] heading 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 = ["*"]