Strengthening MuleSoft API Security with Client ID–Based Resource Restrictions

Introduction: Why Limit Client ID Access?

In today’s API-driven world, security and control are more important than ever. While MuleSoft’s built-in policies like Client ID Enforcement provide essential access control, they often fall short when you need fine-grained access restrictions — like limiting specific client applications to only certain API endpoints. This is a common need in multi-tenant architectures, regulated industries, or when exposing different parts of an API to different partners.

To meet this challenge, MuleSoft allows you to build custom API policies that extend its default behavior. In this guide, we’ll walk through the steps to create a custom policy that restricts access to specific endpoints based on the Client ID. This gives you more control over how your APIs are consumed — without duplicating APIs or writing additional backend logic.

1. Setting Up a Project with the Archetype

The first step in developing a custom policy is setting up a project with the required files. The easiest way to gather all necessary files is by using Maven's archetype. To do this, configure Maven’s settings.xml file as follows:

Maven settings.xml Configuration:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
            http://maven.apache.org/xsd/settings-1.0.xsd">

<servers>
    <server>
      <id>exchange-server</id>
      <username>ANYPOINT PLATFORM USERNAME</username>
      <password>ANYPOINT PLATFORM PASSWORD</password>
    </server>
    <server>
        <id>Repository</id>
        <username>NEXUS USERNAME</username>
        <password>NEXUS PASSWORD</password>
    </server>
</servers>

<profiles>
   <profile>
     <id>archetype-repository</id>
     <repositories>
       <repository>
         <id>archetype</id>
         <name>Mule Repository</name>
         <url>https://repository-master.mulesoft.org/nexus/content/repositories/public</url>
         <releases>
           <enabled>true</enabled>
           <checksumPolicy>fail</checksumPolicy>
         </releases>
         <snapshots>
           <enabled>true</enabled>
           <checksumPolicy>warn</checksumPolicy>
         </snapshots>
       </repository>
     </repositories>
   </profile>
</profiles>
</settings>        

Place the above XML configuration in your settings.xml file and replace the following placeholders:

• ANYPOINT PLATFORM USERNAME and ANYPOINT PLATFORM PASSWORD with your Anypoint Platform credentials.
• NEXUS USERNAME and NEXUS PASSWORD with your Nexus credentials.

Creating the Project:

Once Maven is configured, follow these steps to create the project:

1. Create a new directory for the custom policy project.
2. Navigate to that directory in the command line.
3. Run the following command to generate the project structure:

mvn -Parchetype-repository archetype:generate -DarchetypeGroupId=org.mule.tools -DarchetypeArtifactId=api-gateway-custom-policy-archetype -DarchetypeVersion=1.1.0 -DgroupId=${orgId} -DartifactId=${policyName} -Dversion=1.0.0-SNAPSHOT -Dpackage=mule-policy        

Replace the following placeholders:

• ${orgId} with your Anypoint Platform Organization ID.
• ${policyName} with the desired name for your custom policy.

4. Before finishing, Maven asks you to set up:

• policyDescription: A brief description of your policy.
• policyName: The identifier name of your policy.

Configuring the Project:

After running the above command, the generated project directory will have a structure similar to:

custom-policy/

├── my-custom-policy.yaml

├── mule-artifact.json

├── pom.xml

└── src

   └── main

       └── mule

           └── template.xml

#ClientIdPerResource.yaml file
#%Policy Definition 0.1
id: Client ID per resource
name: Client ID per resource
description: Restrict specific Client Applications to access specific resources. This policy must be used with the Client ID enforcement policy, as the Client ID/Secret will NOT be validated in this policy.
category: Custom
type: custom
resourceLevelSupported: true
encryptionSupported: false
standalone: true
supportedJavaVersions: ["1.8", "11","17"]
requiredCharacteristics: []
providedCharacteristics: []
configuration:
  - propertyName: clientIdExpression
    name: Client ID Expression
    description: Mule Expression to be used to extract the Client ID from API requests
    type: string
    defaultValue: "attributes.headers['client_id']"
    optional: false
    sensitive: false
    allowMultiple: false
  - propertyName: clientIDs
    name: Client IDs restricted
    description: Comma separated list of restricted Client IDs
    type: string
    optional: false
    sensitive: false
    allowMultiple: true
    defaultValue: []        

Modify the Project Files:

1. pom.xml: Replace the generated pom.xml file with the pom.xml provided in the zip file. Ensure that you replace {orgId} with your Anypoint Platform Organization ID.
2. template.xml: Delete the template.xml file generated by the Maven Archetype and replace it with the template.xml file from the given zip file.
3. <policy-name>.yaml: Delete the content of the my-custom-policy.yaml file and replace it with the content from the ClientIDPerResource.yaml file in the zip.

1. Packaging the Policy

Ensure that the Mule Maven Plugin is added to your pom.xml file. This is automatically done by the custom policy archetype. If not, add the following plugin section to your pom.xml:

<plugin>
  <groupId>org.mule.tools.maven</groupId>
  <artifactId>mule-maven-plugin</artifactId>
  <version>${mule.maven.plugin.version}</version>
  <extensions>true</extensions>
</plugin>        

From the command line, in your project directory, run the package phase to package the custom policy:

mvn clean package

1. Uploading the Custom Policy to Exchange

Once the custom policy is packaged, upload it to Anypoint Exchange using the following command:  mvn clean deploy

• This command will publish the custom policy to Anypoint Exchange, making it available to apply to APIs within the specified organization.

4. Applying the Custom Policy

Once the custom policy is uploaded, apply it to the API you want to protect. Follow the steps below:

• Set Up Client ID Enforcement:

1. Apply the Client ID Enforcement policy to the API.
2. When configuring this policy, select Apply configuration to all API methods & resources.

• Create Client Applications:

1. In Anypoint Exchange, create two or more client applications as required.

• Configure the Custom Policy:

1. In the custom policy configuration, list the Client IDs that will be restricted access to specific resources or endpoints.
2. Use the Apply configuration to specific methods & resources option.
3. Set the methods and resources that will be restricted to the listed Client IDs. For example, you can use a regular expression like (.*/api/indianaHIVClientCenteredNegative.*).

• Example Configuration:

1. If you set up the Client ID Enforcement policy with #[attributes.headers['client_id']] (the default value), then set the same field in the custom policy to attributes.headers['client_id'] without the #[ ] symbols.
2. Add the Client IDs in a comma-separated list.
3. Apply the policy to the required methods and resources, such as /api/indianaHIVClientCenteredNegative.

• Test the Policy:

1. After applying the custom policy, test by sending a request to /api/indianaHIVClientCenteredNegative with a specific Client ID, such as 0e3c2647fa314c2aaf3df836df45035c, along with its associated Client Secret.
2. The request should return a 403 Forbidden error if the Client ID is not permitted to access the resource.

5. Policy Order

Ensure that the custom policy is applied in the correct order as shown below. If the policies are not in the desired order, reorder them to match the required configuration.