Client Security

The Client Security policy can be used to extend client authentication access for your APIs.

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway Policy version
DataPower® API Gateway 2.0.0

This topic describes how to configure the policy in the assembly user interface; for details on how to configure the policy in your OpenAPI source, see client-security.

About

You use the Client Security policy to create an assembly action that's separate from the OpenAPI specification, to allow for more options to authenticate an application. Note that you cannot use the client-security policy to perform rate-limiting enforcement.

In a client security action, you define the following settings.
  • Control whether to stop processing if client security fails. When client security fails, stops assembly processing and returns an error.
  • Control whether to require the client secret. When required, the secret is compared to the registered secret on the application that is identified by the client ID.
  • Define the method to extract client credentials from the request.
    • For all methods except HTTP, use the ID Name and the Secret Name properties to specify the location that contains the ID and the location that contains the secret.
      • When Cookie, specify which cookie.
      • When Context Variable, specify which runtime context variable.
      • When Form, specify the form data.
      • When Header, specify which header.
      • When Query, specify which query parameter.
    • For the HTTP method, use the HTTP Type property to specify the format of the authorization header, which expects the Basic form in the basic base64_id:secret format.
  • Define the method to authenticate the extracted client credentials. The supported methods are Native (this means by using IBM® API Connect), or by using a specified Third party user registry.
    • If Third party, use the User Registry Name property to specify the user-registry to authenticate the extracted client credentials. The supported registry types are LDAP and authentication URL.

Properties

The following table lists the policy properties, indicates whether a property is required, specifies the valid and default values for input, and specifies the data type of the values.

Table 2. Client Security policy properties
Property label Required Description Data type
Title No The title of the policy.

The default value is client-security.

 string
Description No A description of the policy. string
Stop on Error Yes If this setting is enabled, assembly processing stops if client security fails, and an error is returned.

The check box is selected by default.

 boolean
Secret Required Yes If this setting is enabled, the client secret must be sent in the request. The secret is compared to the registered secret on the application that is identified by the client ID.

The check box is selected by default.

 boolean
Credential Extraction Method Yes Select one of the following options to define how the calling application authenticates:
  • Header: client ID and client secret credentials must be supplied in the request header.
  • Query: client ID and client secret credentials must be supplied as query parameters in the request URL.
  • Form: client ID and client secret credentials must be supplied as form data sent in a POST request.
  • Cookie: client ID and client secret credentials must be supplied in a header called Cookie.
  • HTTP: the calling application must authenticate by using basic authentication.
  • Context Variable: the credentials that are used for authenticating the client are obtained from context variables that you set in the assembly flow prior to the Client Security policy, by using a GatewayScript policy for example. The names of these context variables are determined by the values that you supply in the ID Name and Secret Name properties of the Client Security policy.

The default value is Header.

 string
ID Name Yes, unless the selected value of Credential Extraction Method is HTTP The name of the parameter whose value specifies the client ID. For all Credential Extraction Method options other than Context Variable and HTTP, the calling application must supply a parameter with this name, in the location defined by the Credential Extraction Method option. For the Context Variable option, this property specifies the name of a context variable.

This property does not apply if the Credential Extraction Method is HTTP.

 string
Secret Name Yes, if Secret Required is enabled and the selected value of Credential Extraction Method is other than HTTP The name of the parameter whose value specifies the client secret. For all Credential Extraction Method options other than Context Variable and HTTP, the calling application must supply a parameter with this name, in the location defined by the Credential Extraction Method option. For the Context Variable option, this property specifies the name of a context variable.

This property does not apply if the Credential Extraction Method is HTTP.

 string
HTTP Type Yes, if the selected value of Credential Extraction Method is HTTP The authentication type. Currently, the only available option is Basic.  
Authenticate Client Method Yes Select one of the following options:
  • Native: only client ID and client secret are used to authenticate the client. If the selected value of Credential Extraction Method is HTTP then the calling application must supply the client ID for the user name, and the client secret for the password.
  • Third party: a user registry is used to authenticate the client. If the selected value of Credential Extraction Method is other than HTTP then the calling application must supply the user name for the client ID, and the password for the client secret.

The default value is Native.

 string
User Registry Name Yes, if the selected value of Authenticate Client Method is Third party Select the user registry that will be used to authenticate the client. The supported registry types are LDAP and authentication URL. string