Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Gateway
  3. Included Policies
  4. Included Policies Directory

  5. Client ID Enforcement

Client ID Enforcement Policy

Policy Name

Client ID Enforcement

Summary

Allows access only to authorized client applications

Category

Compliance

First Mule version available

v3.8.0

Returned Status Codes

401 - Unauthorized or invalid client application credentials

500 - Bad response from authorization server, or WSDL SOAP Fault error

Summary

The Client ID Enforcement policy restricts access to a protected resource by allowing requests only from registered client applications. The policy ensures that the client credentials sent on each request have been approved to consume the API.

When a client application is registered in Anypoint Platform, a pair of credentials consisting of a client ID and client secret is generated. When the client application requests access to an API, a contract is created between the application and that API. An API that is protected with a Client ID Enforcement policy is accessible only to applications that have an approved contract.

When you apply a Client ID Enforcement policy, access to your API is tracked by reporting the client ID along with the analytics events. You can configure Mule runtime engine (Mule) to encrypt all sensitive information that pertains to policies, contracts, and initialization data.

Default policies that internally enforce client application credentials include:

Although token enforcement policies can optionally skip client validation, it is recommended that you enforce the validation to ensure that the token is associated to an approved contract.

Configuring Policy Parameters

Mule Gateway

When you apply the policy to your API from the UI, a list of parameters are displayed based on whether your environment includes Mule or non-Mule applications.

Configuring the Parameters

For Mule applications, the following parameters are displayed:

Parameter Description Required

Credentials origin

Specifies from where in the request to extract the values:

  • HTTP Basic Authentication Header: Requires credentials as part of the authorization header. The application consuming the API must use the basic authentication scheme to send the credentials in the requests.

  • Custom Expression: Accepts an expression each for client ID and client secret, indicating where to extract the credentials from the request. For Mule 3, use MEL Expressions and for Mule 4 and Flex, use a DataWeave 2.0 expression. Use this option to send the credentials in a custom header or any other format. You can leave the field blank to configure the client secret requirement as optional.

Must choose from one of the options.

Client ID Expression

The DataWeave 2.0 expression to use for obtaining the client ID from API requests.

Yes.

Client Secret Expression

The DataWeave 2.0 expression to use for obtaining the client secret from API requests.

No.

Method & Resource conditions: Apply configurations to all API methods & resources

Choose this option if you require the policy to be applied to all the methods and resources associated with the API.

Must choose from one of the options.

Method & Resource conditions: Apply configurations to specific methods & resources

Choose this option if you require the policy to be applied to only specific methods and resources associated with the API.

Must choose from one of the options.

Configuring the Parameters for Anypoint Service Mesh (Non-Mule Applications)

For Anypoint Service Mesh (non-Mule applications), you configure the Client ID Enforcement policy in the same way, excluding the following differences:

Element Description Required

Credentials origin

Specifies from where in the request to extract the values:

  • client_id and client_secret Headers:

  • HTTP Basic Authentication Header: Requires credentials as part of the authorization header. The application consuming the API must use the basic authentication scheme to send the credentials in the requests.

  • Custom Headers: Accepts a header name each for client ID and client secret, indicating from which header to extract the credentials from the request. Use this option to send the credentials in a custom header.

Must choose from one of the options.

Client ID Header

The header name to be used to extract the client ID from API requests.

Yes.

Client Secret Header

The header name to be used to extract the client Secret from API requests

No.

How This Policy Works

Before a client application is allowed to consume an API protected by a Client ID Enforcement policy, the client application must request access to the API. After an approved contract exists between the client application and the API, every request must include the client application credentials in compliance with how the policy is configured.

For example, if the policy is configured to expect a client ID and client secret as query parameters, the application must send those credentials in the request. To enforce this, add a client-id-required RAML trait to the API specification:

traits:
  client-id-required:
    queryParameters:
      client_id:
        type: string
      client_secret:
        type: string

Apply the trait to the resources or methods using the is RAML attribute:

/example:
  get:
    is: [client-id-required]
    description: Example description

Configuring How the Policy Obtains Credentials

You can configure the policy to extract either both the client ID and client secret, or only the client ID from the HTTP request by using a variety of custom DataWeave 2.0 expressions. The following examples use a client ID of '1234' and a client secret of 'abcd'.

Obtaining Credentials Using HTTP Headers

Example request using curl:

curl "http://localhost/myResource" -H "client_id:1234" -H "client_secret:abcd"

Example DataWeave 2.0 expression to be used when configuring the policy:

#[attributes.headers['client_id']]
#[attributes.headers['client_secret']]

In this example, the policy is configured to expect two headers: client_id and client_secret, with the pair of credentials. The policy is flexible to allow other types of headers also. This is the default configuration for the policy.

Obtaining Credentials Using HTTP Query Parameters

Example request using curl:

curl "http://localhost/myResource?client_id=1234&client_secret=abcd"

Example DataWeave 2.0 expression to be used when configuring the policy for Mule 4:

#[attributes.queryParams.'client_id']
#[attributes.queryParams.'client_secret']

In this example, the requester must send the two specified query parameters with the request. Although this is a supported configuration, it poses possible security risks. The recommended method is to use headers. DataWeave 2.0 is fully supported in Mule 4 as wells as a subset in Flex.

Example MEL expression to be used when configuring the policy with headers for Mule 3:

#[message.inboundProperties['client_id']]
#[message.inboundProperties['client_secret']]

Obtaining Credentials Using HTTP Request Payload (Mule only)

Example request using curl:

curl "http://localhost/myResource" -d '{"client_id":"1234", "client_secret":"abcd"}' -X POST

Example DataWeave 2.0 expression to be used when configuring the policy:

#[payload.client_id]
#[payload.client_secret]

Although you can configure the policy to obtain the credentials from the request payload, this option is not recommended because it is harder to reflect in the API specification.

Obtaining Credentials Using Basic Authorization header

Example request using curl:

curl "http://localhost/myResource" -u 1234:abcd

Configuring API Specifications

The Client ID Enforcement policy requires changes in your API specification to implement the credentials requirement. You can find the RAML or OAS snippet link containing the RAML or OAS code you need to add to the API specification in the corresponding policy. You can access this code from the list of applied policies in the Policies tab of your API specification in API Manager.

Policy Output

When an HTTP request is performed against a protected resource for which the Client ID Enforcement policy is applied, and the client application credentials are invalid or unauthorized, the HTTP response includes a WWW Authenticate header with the following values:

Custom mode

Header 'WWW-Authenticate'='Client-ID-Enforcement'

Basic Auth mode

Header 'WWW-Authenticate'='Basic realm="mule-realm"

For SOAP applications, the response is a SOAP error.

See Also