Create the attribute connectors

Attribute connectors let ADS retrieve attribute values that the access request does not contain, from Policy Information Points (PIPs) such as databases, directories, and business services. For example, the request contains only the user's identity, and an attribute connector looks up the user's role and location. Retrieved attribute values can also be cached for improved performance.

Each attribute connector is one YAML file in src/authorizationDomain/attributeConnectors/. It has input attributes, the keys it looks up the values by, and output attributes, the values it provides. All of them must be defined in attributes.yaml, see Create the dictionary.

1. Delete the example attribute connector of the APD distribution in src/authorizationDomain/attributeConnectors/.

2. Create an attribute connector. The following connector provides the role and the location of a user by the user's identity, from JSON data in the connector itself. It needs the attribute acme.user.identity in attributes.yaml, in addition to the attributes of the earlier steps:

   src/authorizationDomain/attributeConnectors/userDirectory.yaml

   className: com.axiomatics.attributeconnector.parser.json.ConnectorModule
   providedAttributes:
     - attributeName: acme.user.role
     - attributeName: acme.user.location
   configuration:
     identifier: userDirectory
     source:
       json:
         value: |
           {
             "users": {
               "cecilia": { "role": "consultant", "location": "london" },
               "martin": { "role": "manager", "location": "stockholm" }
             }
           }
     mappings:
       - attributeName: acme.user.role
         jsonPath: $.users['##1##'].role
         keys:
           - attributeName: acme.user.identity
       - attributeName: acme.user.location
         jsonPath: $.users['##1##'].location
         keys:
           - attributeName: acme.user.identity

   • className is the type of the attribute connector, see the table below.
   • providedAttributes are the output attributes.
   • configuration depends on the type of the attribute connector. Here, each mapping provides one attribute: keys are its input attributes, and ##1## in jsonPath is replaced with the value of the first key.

   Data in the connector itself is useful to get started and for tests. In production, an attribute connector usually calls a service, a database, or a directory, see the example below.

3. Test the policy with the attribute connector. A test with withAttributeConnectors() lets ADS retrieve the attributes that the request does not contain:

   src/test/java/com/acme/MySystemTest.java

   @RegisterExtension
   public AlfaExtension alfa = new AlfaExtension().withAttributeConnectors();
   
   @Test
   @DisplayName("REQ-ABAC-1: Should permit consultant Cecilia to access a resource in London")
   public void shouldPermitCeciliaInLondon() {
       TestResponse result = alfa.newTestRequest()
               .with(Dictionary.ACME_USER_IDENTITY, "cecilia")
               .with(Dictionary.ACME_RESOURCE_LOCATION, "london")
               .evaluate();
   
       assertThat(result, is(permit()));
   }

   The request contains only Cecilia's identity and the location of the resource. The attribute connector provides her role and location, and the policy of Write ALFA policies permits the request.

The following built-in attribute connectors are available. For a custom attribute connector, use its class name.

Attribute connector	Class name
LDAP	com.axiomatics.acs.plugin.pips.ldap.LdapPipModule
SQL	com.axiomatics.acs.plugin.pips.sql.SqlPipModule
Table	com.axiomatics.acs.plugin.pips.table.TablePipModule
HTTP	com.axiomatics.attributeconnector.http.ConnectorModule
JSON Parser	com.axiomatics.attributeconnector.parser.json.ConnectorModule
JWT Parser	com.axiomatics.attributeconnector.parser.jwt.ConnectorModule
XML Parser	com.axiomatics.attributeconnector.parser.xml.ConnectorModule

For the configuration of each type, see the Attribute connectors documentationOpens in a new tab.

note

Attribute connectors with a configurationString instead of configuration use the legacy format. APD upgrades the built-in attribute connectors to the configuration format, see Upgrade legacy attribute connectors. Custom attribute connectors may still require configurationString.

Example: HTTP attribute connector chained to a JSON parser

A common scenario is retrieving attribute values from a REST API. An HTTP attribute connector calls the API and provides the response body as an attribute. A JSON parser attribute connector uses that attribute as its input and extracts the value you need.

src/authorizationDomain/attributeConnectors/userHttpService.yaml

className: com.axiomatics.attributeconnector.http.ConnectorModule
providedAttributes:
  - attributeName: user.service.http.body
configuration:
  identifier: userHttpService
  connection:
    url: ${USER_SERVICE_URL}/users/search
    method: POST
  mappings:
    - attributeName: user.service.http.body
      contentType: application/json
      template:
        payload: true
        value: '{"userId": "@var1"}'
      keys:
        - attributeName: user.identity

src/authorizationDomain/attributeConnectors/userHttpServiceParser.yaml

className: com.axiomatics.attributeconnector.parser.json.ConnectorModule
providedAttributes:
  - attributeName: user.clearance
configuration:
  identifier: userHttpServiceParser
  source:
    attributeName: user.service.http.body
  mappings:
    - attributeName: user.clearance
      jsonPath: $.clearance

The HTTP attribute connector sends the user's identity (@var1, the value of the first key) in the request body and provides the response body as user.service.http.body. The JSON parser attribute connector reads user.service.http.body as its source and provides user.clearance. ADS resolves the chain by itself: a policy that uses user.clearance only needs user.identity in the request. For a test of the chain, see Chained attribute connectors.

tip

You can use environment variables in all attribute connector configurations, such as ${USER_SERVICE_URL} above. See Environment variables for details. This is useful for passwords and other secrets, and for URLs that differ between environments.

Attribute connector tests

Test your attribute connectors during development. PIPs hold data outside your control, so mock them, for example with WireMock, rather than using these tests as acceptance tests. See Attribute connector tests for details.

Attribute cache

To improve performance, attribute values retrieved from attribute connectors can be stored in a cache. The configuration is stored in src/authorizationDomain/attributeCache.yaml. For more information, see the Attribute cachingOpens in a new tab section of the Access Decision Service (ADS) documentation.