API Authentication & Authorization - Configuration Guide

This guide explains how to enable or disable API Authentication (verifying who is calling your API) and API Authorization (controlling what they are allowed to do) in your CX deployment using Application Gateway and IAM.

• API authentication is the process of validating an entity's credentials to prove they are who they claim to be, granting entry to the system.

• API authorization is the process of controlling access to specific resources and actions based on the permissions granted to an authenticated entity. 

Before You Start

You need the following values before you apply any configurations for API security.

• yourRealm: Your tenant ID or realm name (e.g., expertflow) used in IAM.

• client_secret: Your IAM client’s secret. You can find it in: IAM Admin Console > Your Realm > Clients > cim > Credentials > Client secret.

  

Steps to Configure Authentication & Authorization

1. On your server where CX is deployed, go to the folder that contains deployment files.

2. Navigate to /kubernetes/helm-values.

3. Inside this folder, you’ll find a file named apisix-custom-values.yaml.

4. In this file, under apisixStandalone.routes, locate the route (API endpoint) on which you want to enable authentication or authorization.

5. For example, the route for Conversation Manager is given below:

   YAML

   - id: ef-cx-conversation-manager-main
     uris: ["/conversation-manager/*"]
     hosts: ["{{ .Values.global.ingressRouter }}"]
     priority: 0
     service_id: svc-conversation-manager
     status: 1
     plugins:
   #    openid-connect: ...
   #    authz-keycloak: ...

6. You’ll find openid-connect and authz-keycloak plugins under the plugins section of the route.

7. By default, the plugins are disabled (commented out) in the routes. To enable or disable authentication or authorization, simply uncomment or comment the relevant lines. In YAML files, a line is commented out by adding a # at the beginning. Removing the # enables (uncomments) the line.

8. To enable authentication, uncomment the openid-connect plugin block:

   YAML

   openid-connect:
     enable: true
     discovery: "http://keycloak.ef-external.svc/auth/realms/yourRealm/.well-known/openid-configuration"
     realm: "yourRealm"                                   # your tenant ID or realm name
     client_id: "cim"                                     # IAM client-id
     client_secret: "ef61df80-061c-*******-387e6bf67052"  # IAM client-secret
     bearer_only: true
     token_signing_alg_values_expected: "RS256"
     set_access_token_header: false
     set_userinfo_header: false
     audience: ["cim", "account", "realm-management"]
     required_scopes: ["email", "profile"]

   -> To disable authentication, comment out this block again.

9. To enable authorization, uncomment the authz-keycloak plugin block:

   YAML

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

   -> To disable authorization, comment out this block again.

10. After enabling or disabling a plugin, exit /helm-values directory and go back to /kubernetes directory. Run the following command:

    CODE

    helm upgrade --install --namespace ef-external --values helm-values/apisix-custom-values.yaml apisix expertflow/apisix --version 5.0

11. You’ve successfully enabled or disabled the authentication/authorization.

For resource_registration_endpoint and discovery settings:

• Ensure that, instead of using the FQDN, the Keycloak service name is specified before the /auth subpath as shown above.

• Ensure that your realm name or tenant ID is used instead of "yourRealm".

For details on secured components’ APIs and the access levels assigned to different roles, please refer to the Secured Components document.

IAM Configurations

1. Go to your IAM admin console and select your realm.

2. Click on Clients option in left panel and select cim.

   

3. Go to the Client scopes and click on cim-dedicated under Assigned client scope.

   

4. Click on Add Mapper and then select By configuration.

   

5. Click on Audience.

   

6. Provide name as “fix-audience”. Select cim in Included Client Audience. Check “Add to ID Token” toggle as On and Save.

   

Create Customer User

This user is responsible for creation of Access Token for each customer in Customer Widget.

1. Go to the Users tab in left menu.

   

2. Click on Add User. Provide username as “customer” and toggle Email Verified On. Click Create.

   

3. Once user is created, go to Credentials and click on Set Password. Provide credentials as “customer” and toggle temporary to Off. Click Save.

   

4. Click on the Realm roles and check if the customer role exists. If it exists then skip the creation process, else create a customer role.

   

5. After creating customer user, assign it a customer role. Go to the customer user and the click on Role mapping.

   

6. Click on Assing role and assign customer role to user along with offline_access and uma_authorization.

   

7. Customer user creation is done.