Create the dictionary

Use the data from your business requirements and authorization use cases to define relevant attributes in an attribute dictionary document. A well-structured attribute dictionary enhances communication among stakeholders, including internal teams, PIP owners, and auditors.

Namespace and name	Category	Type	Source	Key	Responsible/SLA	Cardinality	Reference	Description	Examples
acme.user.identity	subject	string	PEP	-	-	1..1	HR AD, 6 character alphanum	Acme employee signature	johsmi, jandoe
acme.customer.identity	resource	string	PEP	-	-	0...*	Salesforce customer id	Customer(s) involved in action	231698, 249111
acme.customer.location	resource	string	Salesforce customer PIP	acme.customer.identity	Business Operation team, 99%	0...*	ISO 3166-1	Customer origin country	SE, US

Important

id is a reserved word in ALFA and can not be used in attribute names. For a full list of reserved words, see the Attribute identifiers section of the Access Decision Service (ADS) documentation.

Define the attributes

Before using attributes in ALFA policies or attribute connectors, you should first define them in the appropriate dictionary:

• src/authorizationDomain/alfaSpecifications/attributes.alfa:

  This file contains attributes used in ALFA policies and in tests. These are referred to as policy attributes.

• src/authorizationDomain/attributes.yaml

  This file contains attributes used as input and output by attribute connectors. These are referred to as attribute connector attributes.

tip

Some attributes must be defined in both dictionaries because attribute connector output attributes are used in policies.

Policy attributes

To use an attribute in an ALFA policy or JUnit test, define it in an ALFA file within the authorizationDomain directory. Organize your attributes into hierarchical namespaces as needed.

attributes.alfa

    namespace acme {
           namespace user {
            attribute role {
                id = "acme.user.role"
                type = string
                category = subjectCat
            }
        }

        namespace resource {
            attribute location {
                id = "acme.resource.location"
                type = string
                category = resourceCat
            }

            attribute identity {
                id = "acme.resource.identity"
                type = string
                category = resourceCat
            }
        }
    }

• The id should always be the concatenated namespaces, separated by dots, plus the attribute name.
• type should be one of the JSON shorthand type codes listed in section3.3.1 Supported Data TypesOpens in a new tab of the JSON Profile of XACML 3.0 Version 1.0 specification.
• category can be subjectCat, resourceCat, actionCat, or environmentCat and it specifies whether the attribute is a property of a subject (for example, role), resource (for example, document), etc.
• This file uses the ALFA format. Attributes can be defined in any ALFA file, not just attributes.alfa.

Attribute connector attributes

Attributes used by attribute connectors, whether as input or output, must be defined in the attributes.yaml file, which uses the YAML format. Learn more in the YAML-format domain file analysis section of the Access Decision Service (ADS) documentation.

attributes.yaml

acme.user.role:
  xacmlId: acme.user.role
  category: AccessSubject
  datatype: string
acme.user.location:
  xacmlId: acme.user.location
  category: AccessSubject
  datatype: string
acme.resource.location:
  xacmlId: acme.resource.location
  category: Resource
  datatype: string

• For convenience, xacmlId can be set to concatenated namespaces, separated by dots, plus the attribute name.
• category can be AccessSubject, Resource, Action or Environment and it specifies whether the attribute is a property of a subject (for example, role), resource (for example, owner), etc.
• datatype should be one of the JSON shorthand type codes listed in section3.3.1 Supported Data TypesOpens in a new tab of the JSON Profile of XACML 3.0 Version 1.0 specification.
• This file uses the YAML format.