Security Scheme

Security for your application ecosystem is not only about knowing APIs within it, but also ensuring that the right users with the right privileges can access these APIs. The Security Scheme in Traceable is a powerful role- and scope-based access control for APIs in your application ecosystem. It leverages both dynamic learning and manual definition to prevent unauthorized API access. These schemes allow you to enforce accurate authorization rules based on your application and API architecture. This security scheme helps you enhance API security while ensuring authorized access and flexibility.

What will you Learn from this Topic?

By the end of this topic, you will understand:

What is a Security Scheme, and how can you use it to prevent unauthorized access to APIs.
What are the methods of security scheme configuration: Auto-learned and User-defined, and the difference between them.
How to configure role or scope mapping.

What is a Security Scheme and How does it Help?

A Security Scheme is a guideline that secures your APIs against unauthorized access, data breaches, and Broken Function-Level Authorization (BFLA) attacks. It works in coexistence with User Attribution, which helps Traceable gather role and scope information from the incoming API traffic. Once you have set up the user attribution, you can use the security scheme to enforce access control by defining the roles and scopes, and the permitted API endpoints for interaction.

Before You Begin

Before setting up a Security Scheme, you must set up User Attribution. This is required as it allows Traceable to detect user roles and scopes from the incoming traffic. For information on the steps to set this up, see User Attribution.

Understanding Security Scheme

The Security Scheme is created with the idea that every API call is evaluated based on who is asking for it, and what are they allowed to do. In Traceable, the Security Scheme page is a hub where you can manage roles and scopes across all API endpoints. It provides a comprehensive view of the authorized roles and scopes and their related endpoints that you may have configured or Traceable has detected from the incoming traffic. Using this page, you can define the security scheme for your endpoints that helps prevent unauthorized API interactions. To view the Security Scheme page, navigate to Catalog → Settings → Security Scheme.

As mentioned above, you must configure User Attribution to allow Traceable to extract role and scope information from the incoming traffic. Once you have configured user attribution, on the Security Scheme page, Traceable provides two modes of mapping roles and scopes:

Auto-Learn Mode

How it works — If enabled, in this mode, Traceable automatically analyzes the incoming API traffic and maps roles, scopes, and endpoints dynamically. This method is useful if you wish to discover API access patterns without manual intervention.
Note
Traceable auto-learns authenticated APIs only.
Representation — Traceable represents auto-learned roles, scopes, and endpoints using the icon.
Retention — For accuracy and relevance, Traceable automatically purges any auto-learned roles and scopes, and their corresponding endpoints if they are not observed for 7 consecutive days.
Parent Hierarchy — This method does not have a parent role or scope due to dynamic learning.
Endpoint Mapping — Traceable automatically maps the endpoints, where it identifies the role or scope.
Conversion — If you wish to retain a role or scope for long-term enforcement, you can convert it to a user-defined one. This ensures that Traceable retains it until you delete it.

For information on enabling auto-learn and converting a role, scope, or endpoint to user-defined, see the Enabling Auto-Learn and Converting Auto-Learned Schemes to User-Defined sections, respectively.

User-Defined Mode

How it works — In this mode, you can manually define the roles and scopes and the specific endpoints that the assigned users should be able to access. This method is useful if you wish to strictly impose authorizations, especially in environments containing sensitive data.
Representation — Traceable represents user-defined rules, scopes, and endpoints using the icon.
Retention — Traceable retains these configurations until you delete them.
Parent Hierarchy — This method allows you to define a parent role or scope that inherits the access permissions granted to the child role. For example, the Account Owner role (Parent) inherits the permissions granted to the Developer role (Child).
Note
The child role does not inherit access permissions granted to the parent role.
Endpoint Mapping — You can associate or map specific API endpoints that the role or scope can access.

For information on creating a user-defined role or scope mapping, see Creating a User-Defined Scheme.

Setting Up a Security Scheme

Traceable provides you the flexibility to define Security Schemes according to your application architecture and business requirements. This flexibility is provided in the form of Auto-Learn and User-Defined schemes. This section highlights the recommendations on when to use these modes, along with the corresponding steps.

Recommendations

Traceable recommends using:

Auto-Learn mode when you do not have information on your traffic, and want Traceable to learn and create schemes dynamically.
User-Defined schemes when you wish to build access control based on the existing traffic insights.

Enabling Auto-Learn Mode

Auto-Learn allows Traceable to dynamically learn roles, scopes, and their associated endpoints (authenticated) from the incoming traffic. To enable auto-learn for authorized roles or scopes, complete the following steps:

Navigate to the Security Scheme page.
From the page’s top right corner, Environment drop-down, select the environment for which you wish to enable auto-learn. By default, Traceable selects All Environments.
Select the Authorized Roles or Authorized Scopes tab according to your requirements.
Click the Auto-learn toggle to enable it.

Traceable automatically learns the roles or scopes, and the associated endpoints for the environment(s) in which you enabled the option and shows them on the page.

Creating a User-Defined Scheme

You can define the roles, scopes, and endpoints that assigned users can access. To create a user-defined role or scope and select the endpoints, complete the following steps:

Navigate to the Security Scheme page.
From the page’s top right corner, Environment drop-down, select the environment for which you wish to create a user-defined scheme. By default, Traceable selects All Environments.
Select the Authorized Roles or Authorized Scopes tab according to your requirements.
Click the + icon.
In the Create Role/Scope Mapping window, complete the following:
1. Specify the Role/Scope name.
2. (Optional) Select the Parent role/scope.
3. Click + Add to add accessible endpoints. In the Select API Endpoint window that appears, complete the following:
  1. (Optional) Click the Filter () icon to filter endpoints or use the search field to search.
  2. Click Select corresponding to the endpoints you wish to choose.
  3. In the window’s bottom left corner, click Review and verify the selected endpoints.
  4. Click Add once you have verified the selected endpoints.
4. Click Create.

The following demo shows how to perform these steps in the Traceable platform.

Traceable creates the role or scope and shows it on the page.

Managing Security Schemes

With your evolving application ecosystem and APIs, the roles and scopes require management as well. Traceable provides you the flexibility to manage the security schemes according to your requirements. Through this management, you can ensure that the access control is correct at all times. This section highlights the steps to convert auto-learned schemes to user-defined, update the schemes, and some additional features available on the page.

Converting Auto-Learned Schemes to User-Defined

Traceable automatically purges any auto-learned roles, scopes, and endpoints if it does not observe any related traffic in 7 consecutive days. This helps maintain the accuracy and relevancy of data. While these auto-learned schemes are purged, the user-defined ones are stored until you delete them explicitly. If you wish to keep the auto-learned schemes in the Traceable platform, you can convert the auto-learned schemes to user-defined.

To convert an auto-learned role, scope, or endpoint to user-defined, complete the following steps:

Navigate to the Security Scheme page.
From the page’s top right corner, Environment drop-down, select the environment for which you wish to convert schemes. By default, Traceable selects All Environments.
Select the Authorized Roles or Authorized Scopes tab according to your requirements.
Depending on the role, scope, or endpoint you wish to convert, complete one of the following:
- To convert a role or scope:
  1. Click the Ellipse () icon corresponding to the auto-learned role or scope, and click Mark as User Defined.
    Note
    Converting a role or scope to user-defined does not automatically convert its endpoints. You must convert each endpoint manually. To do so, complete the below step.
  2. In the confirmation window, click Yes, Mark as User Defined.
- To convert an endpoint:
  1. Click the Ellipse () icon corresponding to the auto-learned role or scope and click Edit.
  2. In the Edit Role/Scope Mapping window, Endpoint section, click the Ellipse () icon and click Mark as User Defined.
    Note
    Converting any auto-learned endpoint for a role or scope to user-defined automatically converts the associated role or scope to user-defined as well.
  3. Click Update.

The following demo shows how to perform these steps in the Traceable platform. It consists of two sections that show how you can convert a role or scope, and an endpoint.

Managing Role and Scope Mappings

To manage the mappings, click the Ellipse () icon corresponding to a role or scope, and you can do the following:

View — View the mapping without making any changes.
Edit — Modify the mapping. If selected, you can modify all the fields and add or remove endpoints according to your requirements.
Delete — Delete the mapping from the Traceable platform.
Note
A deleted mapping cannot be restored.
Mark as User-Defined (for Auto-Learned schemes only) — Convert auto-learned mappings to user-defined. You can do this to ensure that Traceable does not purge the mapping due to unavailable traffic.

Additional Features

Apart from the above features, you can navigate to the respective roles/scopes tab and do the following:

Search — Use the search bar to search for schemes.
Filter — Click the Filter () icon to narrow down the schemes and/or endpoints based on their modes (auto-learn and user-defined).
Bulk Delete — Click the check-box corresponding to the respective schemes and click Delete at the bottom of the page.
Note
Deleted schemes cannot be restored.