Managing API Mappers

General

The API Mappers define the relation between the Applications and Asset Types 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 API Mapper
• Define the Attribute Mapping Logic
• Prioritize the API 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:

1. Match Pattern - A unique value which maps and caches the API URL, allowing the Authorization Platform to access and use. When using:

• One asterisk as a wildcard character, the Match Pattern applies the first subfolder in the directory (for example: /api/v1/account/accounts/* refers to contents within the accounts directory and only the first subfolder).
• Two asterisks as a wildcard, the Match Pattern applies to all subfolders that are after "accounts". “/accounts/**”.
   
  E.g. “/accounts/user” and “/accounts/settings/profile” would still match this pattern, but it would also match URLs like “/accounts/user/posts” or “/accounts/settings/profile/edit”.
   

2. Asset Types - Determines which Asset Type (or Asset Types) are associated to this Mapper (for example: Loan, Account means that the API Mapper is associated to Asset Types Loan and Account).

Both of these values are required

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 being 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.

1. 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:
2. API Mapper name
3. Description (optional)
4. Active (Yes or No)
5. Match Pattern
6. Asset Types (associated to this Application)

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 API Mapper.
5. Enter a Description for the new API Mapper (optional).
6. By default, the API Mapper will be Active. If you wish to disable it initially, click on the blue Active slider. The slider will turn gray and the API Mapper will be inactive.

• 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 API Mapper. This determines which Attributes can be used to define the mapping logic between Attributes defined in the Policy and those in the data repositories of the Organization.
• Click Save. The new API Mapper is added to the API Mapper List.

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

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.

Associating an Asset Type to an API Mapper

After creating the API Mapper, you can then associate the API Mapper to one or more Asset Types.

Note that this can only be done after the Asset Type has been created.

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.

Once you associate an Asset Type to an API Mapper, the API Attribute Mappers section becomes visible. In this section, you can define the API mapping between that Attribute and the value that needs to be considered in the Policy.

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

To associate an Asset Type to an API Mapper:

1. In the Authorization Workspace, select the Application to open the Application Settings screen. This screen lets you manage the Applications and the Asset Types that are associated to them.
2. On the Details page, in the Attribute Mapping Settings section, select Set API Mapping. The Set API Mapping panel opens.
   • Add a new API Mapper by clicking Add.
   • Assign a Name to the new API Mapper.
   • Select the Source (options are; Body, Header, JWT, Path, Query) field
   • Enter the appropriate value (for example, for Path enter the full Path for the API Mapper.
   • 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.

Defining the Source and Path

• In the Source field, select one of the options detailed below.
• 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].