API Authorization - Configuration/Customization Guide

This document is intended for anyone responsible for configuring or managing API authorization settings, including developers, system administrators, and operations teams. They can apply fine-grained authorization on their APIs using this document. By default, APIs of all the components mentioned in Secured Components are secured with authorization. Secured Components document specifies the secured APIs and user roles (e.g., agent, supervisor, admin) that have access to each API, along with the allowed scopes (e.g., GET, POST) for each user role.

The document outlines all the steps for securing APIs with authorization using IAM and the authz-keycloak plugin of Application Gateway. It provides generic templates for applying authorization to various APIs and uses an API from Customer Channel Manager as example.

Considerables

• Wildcard entries for APIs of all the components are already secured, as mentioned in the Secured Components (e.g., /ccm/*, /routing-engine/*, /conversation-manager/*, etc.). The wildcard /ccm/* covers all routes under it, such as /ccm/channel-types, /ccm/channel-provider-interfaces, /ccm/widget-configs, and so on.

• Suppose you’re working with CCM APIs and you want a specific endpoint to be treated differently and should have different access levels than wildcard endpoint (/ccm/*), you will need to perform all the steps outlined in IAM Configurations section. For example, if you choose /ccm/channel-types* endpoint, it will have its own set of authorization rules (including resources, scopes, policies, and permissions) associated with it.

Configurations Required in Application Gateway

By default, all the required routes are secured with authorization in Application Gateway, so no changes are required in the its configuration. To confirm that the component you're working with is secured in Application Gateway, you can search for the following values under the plugins section of your component’s route in the values.yaml file (located under /kubernetes/helm/apisix).

authz-keycloak:
  lazy_load_paths: true
  http_method_as_scope: true
  resource_registration_endpoint: "http://keycloak.ef-external.svc/auth/realms/expertflow/authz/protection/resource_set"
  discovery: "http://keycloak.ef-external.svc/auth/realms/expertflow/.well-known/uma2-configuration"
  client_id: "cim"                                             # keycloak client-id
  client_secret: "ef61df80-061c-xxxx-xxxx-387e6bf67052"        # keycloak client-secret

• To add authorization to a specific route, you need to add authz-keycloak plugin (mentioned above) in plugins section of that route.

• To remove authorization from a route, simply remove the authz-keycloak plugin from the route.

Exception Routes

If /ccm/* is secured with authorization, it means that all the routes falling under /ccm/ are secured. However, if you want to leave /ccm/channel-types* unsecured by removing authorization while keeping all other routes secured, you’ll need to create an Exception Route for /ccm/channel-types* without the authz-keycloak plugin. See Advance API Gateway Routing.

Configurations Required in IAM

To secure an API endpoint with authorization, you must create Resource, Scopes, Policies, and Permissions in IAM for it. These four entities must be configured for authorization to function properly. We'll cover each entity in detail.

To find the settings where you can create these entities, follow the steps below:

1. In Expertflow realm, go to Clients section and select cim.

   

2. Go to Authorization tab. Here you’ll see all the four entities. We’ll cover next steps from here.

   

1. Create Scopes

There can be multiple scopes that need to be created for a resource. You can think of a resource as an API endpoint, and scopes as the actions (verbs/functions) that can be performed on that resource. For APIs, each HTTP method acts as a scope. Following scopes are already created in IAM:

• GET

• PUT

• POST

• DELETE

• PATCH

If there are any other HTTP methods that your API uses or if you can’t find a scope for one of the above mentioned methods, you can create the necessary scopes by following the instructions below.

Number of scopes in a resource depends on the use-case of API you are securing. For example, if you're only securing GET and POST requests for an API, you don’t need to use/define other scopes, as those operations are not relevant in this case. Also, access is dynamic and flexible, you can give access to any user (agent, senior agent, supervisor, admin) based on use-case.

Steps to create Scopes:

1. Select Scopes under Authorization tab.

   

2. In the search box, enter the name of the scope you want to use for your API (e.g., POST). If you find the scope, you’re good to go. Otherwise, you'll need to create the scope by following the next steps.

   

3. Click Create authorization scope.

4. Enter the name of the scope for your API. The scope name should be in capital letters and match the HTTP method (e.g., DELETE).

   

5. Click Save. Your DELETE scope has been created.

6. You can create other scopes in the same way.

7. We’ll use GET, PUT, POST & DELETE scopes with /ccm/channel-types*.

2. Create a Resource

An API endpoint is considered a resource because it serves data or allows you to perform CRUD operations. For each targeted endpoint, a separate resource will be created in IAM. If you target N number of APIs, you will need to create N number of resources. We’ll create a resource for /ccm/channel-types* API below.

Steps to create a Resource:

1. Select Resources under Authorization tab and click Create resource.

   

2. Enter the name of the resource for your endpoint. The resource name should follow the camelCase convention, structured as: <componentName>-<endPoint>-api.

3. Enter your endpoint in the URIs field.

4. Select all the allowed HTTP methods for your API in Authorization scopes field. For example, you can enter GET or POST, and then select them from the drop-down menu.

   

5. Click Save and you have created a resource for an endpoint.

3. Create Policies

Policies in IAM define the conditions under which a specific action or permission is granted to a user, a role, or group of users. You need to create a policy for each scope of a resource. In the example above, since we used four scopes, we will need to create four policies, one for each scope.

Steps to create Policies:

1. Select Policies under Authorization tab and click Create policy.

   

2. Select Role as policy type.

   

3. Enter the name of the policy for GET scope. Policy name should follow this convention: <Resource Name> - <Scope Name> - policy. Note the spaces around dashes/hyphens.

4. Add a description for the policy.

5. Click Add roles and assign all the roles (e.g., agent, supervisor, and admin) that should be able to make GET request to /ccm/customer-topics*.

6. Click Save. You may not see roles listed, but if IAM notifies you about successful policy creation, you’re all set.

   

7. Create a policy for PUT, POST and DELETE scopes in the same way. The differences are as follows:

   1. Scope names are different for the policies.

   2. Only select the roles that are allowed to perform specific actions on the resource. For example, supervisor for POST and admin for DELETE, etc.

   3. If you want to allow an agent to perform CRUD operations on the resource, make sure to select that role as well for other scopes.

8. You have now created policies for the endpoint/resource.

4. Create Permissions - The Final Step

Permissions in IAM define what actions users are allowed to perform on a specific resource. You need to create a permission for each policy related to a resource. In the example above, since we have created four policies for ccm-channelTypes-api resource, we will need to create four permissions, one for each policy.

Step to create Permissions:

1. Select Permission under Authorization tab, click Create permission and select Create scope-based permission.

   

2. Enter the name of the permission for the GET scope/policy. The permission name follows the same convention as the policy, but with the keyword policy replaced by permission.

3. Add a description for the permission.

4. Select the resource you created (e.g., ccm-channelTypes-api).

5. Select the GET scope to allow HTTP GET method for respective resource.

6. Select the GET policy you created for the resource (e.g., ccm-channelTypes-api - GET - policy).

   

7. Click Save.

8. You’ve now created a permission that allows users with the “agent”, “supervisor”, or “admin” role to access the /ccm/channel-types* API using the GET method.

9. You can create permissions for other scopes/policies of the same resource in a similar manner, with the following differences:

   1. Select the appropriate scope (POST, PUT, or DELETE) based on your specific requirements.

   2. Choose the corresponding POST, PUT, or DELETE policy you created for the resource.

   3. For example, for ccm-channelTypes-api - POST - permission, the scope would be and POST. The policy would be ccm-channelTypes-api - POST - policy.

10. This permission will allow users with the “supervisor” or “admin” role to access the /ccm/channel-types* API using the POST method.

Configured Authorization

In the above examples, we have configured authorization for the /ccm/channel-types* endpoint of Customer Channel Manager APIs, such that:

• A user with agent, supervisor, or admin role can make a GET request to the /ccm/channel-types* endpoint.

• A user with supervisor or admin role can make a POST and PUT requests to the /ccm/channel-types* endpoint.

• A user with admin role can make a DELETE request to the /ccm/channel-types* endpoint.

• Any other HTTP methods are not allowed.

GET /ccm/channel-types*
Authorization: Bearer <token>

HTTP/1.1 200
<expected-response>

POST|PUT|DELETE /ccm/channel-types*
Authorization: Bearer <token>

HTTP/1.1 403 Forbidden
{"error":"access_denied","error_description":"not_authorized"}

GET|POST|PUT /ccm/channel-types*
Authorization: Bearer <token>

HTTP/1.1 200
<expected-response>

DELETE /ccm/channel-types*
Authorization: Bearer <token>

HTTP/1.1 403 Forbidden
{"error":"access_denied","error_description":"not_authorized"}

GET|PUT|POST|DELETE /ccm/channel-types*
Authorization: Bearer <token>

HTTP/1.1 200
<expected-response>