Managing API Mappers

The API Mappers define the relation between the Applications, Asset Types, and Identity Sources in the Authorization Platform to the APIs used to access or use the business applications of the Organization.

API Mapper Workflow

Creating and applying API Mappers is typically done in the following stages. Note that until you create the API Mapper, the option to associate it to an Asset Type is not visible. To effectively use API Mappers, you should:

• Create an Application
• Create an Asset Type
• Creating an API Mapper
• Associate the Asset Type to the Mapper
• Associate optional Identity Sources to the Mapper
• Define the Attribute Mapping Logic
• Prioritize the Mappers

API Mappers within the Authorization Platform are created for and must be unique in an Application (click on an Application and select the API Mappers tab).
In addition to a Name and Description (optional), each API Mapper is assigned:

• Match Pattern - A Match Pattern is a unique value used to map and cache API URLs, enabling the Authorization Platform to match and authorize requests efficiently. The match pattern supports wildcards for flexible URI matching:

  • A single asterisk * acts as a wildcard for a single segment of the path. It can be used in two ways:
    • To match a full segment, like /accounts/*/id, where * can represent any one segment (e.g., /accounts/123/id).
    • As part of a segment, such as /acc*/details/id, where the * substitutes part of the segment (e.g., matching /accounts/details/id or /accounting/details/id).
  • A double asterisk ** is a multi-segment wildcard, allowing it to match multiple segments. For example, /accounts/** would match any path starting with /accounts/ and continuing with any number of additional segments, such as /accounts/user, /accounts/settings/profile, or /accounts/user/posts.

This enables flexible and dynamic API URL matching for Authorization purposes.

• Asset Types

  • Defines which Asset Type/s are associated with this Mapper. For example, associating the Asset Types Loan and Account means the Mapper is connected to these business resources. The purpose of associating Asset Types to a mapper is to create a link between the physical layer—the API request—and the logical layer, which represents the protected resource (the Asset Type). This association ensures that dynamic Authorization is applied based on the business resources the API grants access to, allowing for fine-grained control over which logical assets, such as Loan or Account, are accessible and require protection.

• Identity Source (optional)

  • Defines which Identity Source is associated with the mapper. This association adds granularity by specifying which Identity Source should or should not be used for access evaluation for a particular API.

API Mapper Example

An Authorization Policy might be created to ensure that bankers can only access accounts in their region. To determine the appropriate Authorization Decision, the Authorization must be provided with key Attribute information. Within the Authorization Platform the bank may create a rule that states that the Attribute for the Bank Account Location must match the Location Attribute of the user.

The bank would begin by creating an Internal Bank Portal Application. An Asset Type would contain the Attributes required. For example: the first and last name of each banker. The banker's department, branch, bank_region, and userid might also be included in this Asset Type definition.

Another Asset Type might be included for the bank's servers where the accounts are maintained. Here too, there might be Attributes such as account_type, server_type, server_department, server_region. Ultimately, the API Mappers would be responsible for providing the server_region and bank_region Attribute values to the Authorization Platform either in the actual Request or by pointing the Authorization Platform to where these Attributes are available.

All currently defined API Mappers associated with an Application are listed in the API Mapper List on the Application's Settings screen. When you click on an API Mapper, the Details section displays the current parameter definitions for that API Mapper, including:

• API Mapper name
• Description (optional)
• Active (Yes or No)
• Match Pattern
• Asset Types (associated to this Application)
• Identity Source

Adding an API Mapper

To add an API Mapper:

1. In the Authorization Workspace, select an Application. The Application Settings screen is displayed.
2. Select the API Mapper tab. The API Mapper List is displayed.
3. Click Create. The API Mapper Details screen is displayed with the parameters that need to be defined.
4. Enter a Name for the new Mapper.
5. Enter a Description for the new Mapper (optional).
6. By default, the Mapper is Active. If you wish to disable it initially, click on the blue Active slider. The slider will turn gray and the Mapper will be inactive.
   6.1 In the Settings section:
   • Enter the Match Pattern. Note that this value must be unique per Application.
   • Use the drop-down arrow to select which Asset Type to associate to this Mapper. This determines which Asset Type is enforced for access and would be represented by Attributes mapped to the API request being processed.
   • In the Identity Source Association section, you can toggle whether Identity Sources should be filtered in the Mapper evaluation. You can choose filtering by choosing to either Include or Exclude identity sources. See the section on Unavailable Identity Sources for more information.
   • Click Set an Identity Source to open a side panel with all available Identity Sources (Aux or Context). To complete this step, ensure that you choose a valid Identity Source for the relevant Mapper. This capability complements the management of unavailable or unnecessary sources during PDP calculations.
     • Note: If the Identity Source toggle is off, all Identity Sources will be part of the access decision calculation.
7. Click Save. The new Mapper is added to the API Mapper List.

Associating an Asset Type to an API Mapper

After creating the API Mapper, you can then associate the Mapper to one or more Asset Types.
*Note that this can only be done after the Asset Type has been created and linked to the Application.

Associating an API Mapper to an Asset Type enables you to use Attributes associated with the Asset Type to define the logic mapping the Organization's APIs to the Attributes in the Authorization Platform.

After associating the Asset Type(s) to the API Mapper, you need to define the Attribute mapping logic.

Once you associate an Asset Type to an API Mapper, the API Attribute Mappers section under the Asset Attributes tab becomes visible. In this section, you can define the API mapping between an Attribute and the source location in the API request from which the Asset value is fetched.

To map an Asset Attribute to an API Mapper:

1. In the Authorization Workspace, select the relevant Asset Type to open the Asset Type Settings screen. This screen lets you manage the Applications and the Asset Types that are associated to them.
2. Select the Asset Attribute tab.
3. Select the relevant Asset Attribute from the list or create one.
4. Under Attribute Mapping Settings, select Set API Attribute Mapping.
5. The Set API Attribute Mapping panel opens.
   • Add a new API Mapper by clicking Add.
   • Assign an API Mapper Name to the new API Mapper.
   • Select the Source (options are; Body, Header, JWT, Path, Query) field.
   • Enter the Path. This can be a JSON Path or other relevant Path.
   • Enter the appropriate value.
   • Click Done.

Note: You can only add or delete an API Attribute Mapper.

Associating an Identity Source to an API Mapper

When creating or editing an API Mapper, you can enable or disable the association of Identity Sources to the mapper. This allows customers the ability to granularly define which Identity Sources are used for a specific API access calculation while allowing unneeded sources to be filtered to avoid data fetching and reduce performance impact.
Since Main sources cannot be filtered, this option is limited to AUX/Context sources.

This API Mapper association leverages the operationalFilters parameter in the relevant Runtime APIs and creates a filter as part of the preprocessing phase in the PDP based on the mapping.

Note that if operationalFilters are provided in the Runtime request directly, they will override the Mapper's settings. This override mechanism is particularly useful for troubleshooting and testing scenarios, such as when using Postman to manually adjust and refine the API response.

Associating an Action to an API Mapper

When managing an API Mapper, you can associate it with specific Actions connected to an Asset Type.
Note that the Action must be linked to an Asset Type before associating it with an API Mapper.

Associating an API Mapper with an Action allows the Action’s attributes to be mapped to values derived from the API request, enabling precise authorization logic in the Authorization Platform.

To map an Action to an API Mapper:

1. In the Authorization Workspace, select the relevant Asset Type to open the Asset Type Settings screen. This screen lets you manage the Actions and the Asset Types.
2. Select the Actions tab.
3. Select the relevant Actions from the list or create one.
4. Under API Action Mappers, select Set API Action Mapping.
5. The Set API Action Mapping panel opens.
   • Add a new API Mapper by clicking Add.
   • Assign an API Mapper Name to the new API Mapper.
   • Select the Source (options are; Body, Header, JWT, Path, Query) field.
   • Enter the Path. This can be a JSON Path or other relevant Path.
   • Enter the appropriate value.
   • Click Done.

Defining the Attribute Mapping Logic

After creating the API Mapper and associating one or more Asset Types to it, you need to define the Attribute mapping logic. Essentially, this defines the location where the Authorization Platform can find the Attribute values.

For example, if a global bank has a Policy that states that bankers can only access accounts in their region, the API Mappers would define where the Authorization Platform can retrieve the Attribute values to determine whether the banker and account are in the same region. If this is confirmed, the Authorization Platform can return a response indicating that the Authorization decision would be to allow access.

Defining the Source and Path

For each Asset Attribute in the Policy, you can define the Source and Path that the API Mapper will use. This is done in the API Attribute Mappers section on the Asset Attributes tab of the Asset Type Settings screen.

To set the Source and Path for an Attribute:

1. In the Authorization Workspace, select the Assets & Conditions tab.
2. In the Asset Types section, select the Asset Type in which you wish to define the API Mapper for the Asset Attribute. The Attributes List is displayed.
3. In the Asset Attributes tab, select the Attribute.
4. In the Mapping section, click API Mapping. The Set API Mapping panel is displayed.
5. Click Add.
6. In the Source field, select the appropriate Source.
7. In the Path field, enter the appropriate information.

Path Mapping Example

In the following example, two Attributes are included in the API call. The API Mapper defines the user Attribute value by the path [4] and the account Attribute by the path [6].

Editing an API Mapper

To edit an API Mapper:

1. In the Authorization Workspace, select an Application. The Application Settings screen is displayed.
2. Select the API Mapper tab. The API Mapper List is displayed.
3. Select the API Mapper in the API Mapper List and click Edit. You can now edit all fields as needed.
4. Click Save to save your changes.

Deleting an API Mapper

To delete an API Mapper:

1. In the Authorization Workspace, select an Application. The Application Settings screen is displayed.
2. Select the API Mapper tab. The API Mapper List is displayed.
3. Hover over the API Mapper you want to delete and click the trash icon.
4. In the Delete this API Mapper? warning message, click Delete.