client-security

The client-security policy can be used to extend client authentication access for your APIs.

Gateway support

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 your OpenAPI source; for details on how to configure the policy in the assembly user interface, 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-var, 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 property to specify the user-registry to authenticate the extracted client credentials. The supported registry types are LDAP and authentication URL.

Properties

The client-security policy has the following format:

- client-security:  
    version: version
    title: title
    description: description
    stop-on-error: is_processing_stopped_on_client_security_failure
    secret-required: is_client_secret_required_in_request
    extract-credential-method: method_for_supplying_credentials
    id-name: parameter_that_specifies_client_id
    secret-name: parameter_that_specifies_client_secret
    http-type: authentication_type
    client-auth-method: method_for_client_authentication
    user-registry: user_registry_for_client_authentication
Table 2. client-security policy properties
Property Required Description Data type
version Yes The policy version number. string
title No The title of the policy. string
description No A description of the policy. string
stop-on-error Yes If set to true, assembly processing stops if client security fails, and an error is returned. boolean
secret-required Yes If set to true, 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. boolean
extract-credential-method Yes Specify one of the following values 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-var: 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 GatewayScript policy is available only with the Premium subscription.

string
id-name Yes, unless extract-credential-method is set to http The name of the parameter whose value specifies the client ID. For all values of extract-credential-method other than context-var and http, the calling application must supply a parameter with this name, in the location defined by the extract-credential-method setting. For context-var, this property specifies the name of a context variable.

This option does not apply if the extract-credential-method property is set to http.

 string
secret-name Yes, if secret-required is set to true and extract-credential-method is other than http The name of the parameter whose value specifies the client secret. For all values of extract-credential-method other than context-var and http, the calling application must supply a parameter with this name, in the location defined by the extract-credential-method setting. For context-var, this property specifies the name of a context variable.

This option does not apply if the extract-credential-method property is set to http.

 string
http-type Yes, if extract-credential-method is set to http The authentication type. Currently, this must be set to basic. string
client-auth-method Yes Specify one of the following values:
  • native: only client ID and client secret are used to authenticate the request. If extract-credential-method is set to 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 extract-credential-method is set to a value other than http then the calling application must supply the user name for the client ID, and the password for the client secret.
 string
user-registry Yes, if the client-auth-method is set to third-party Specify the value of the name property of the user registry that will be used to authenticate the client. The supported registry types are LDAP and authentication URL. string

client-security policy example


- client-security:
    version: 2.0.0
    title: client-security
    stop-on-error: true
    secret-required: true
    extract-credential-method: cookie
    id-name: my-client-id
    secret-name: my-client-secret
    client-auth-method: third-party
    user-registry: myauthurl