Enforcing security requirements on an operation

To enforce security requirements on an API operation, you apply previously created security scheme components that define various aspects of API security configuration.

About this task

Note:
  • This task relates to configuring an OpenAPI 3.0 API definition. For details on how to configure an OpenAPI 2.0 API definition, see Editing an OpenAPI 2.0 API definition.
  • OpenAPI 3.0 APIs are supported only with the DataPower® API Gateway, not with the DataPower Gateway (v5 compatible).
  • For details of current OpenAPI 3.0 support limitations, see OpenAPI 3.0 support in IBM® API Connect.

You can complete this task either by using the API Designer UI application, or by using the browser-based API Manager UI.

For details on how to create and configure security scheme components, see Defining security scheme components.

A security requirement specifies one or more security scheme components whose conditions must all be satisfied for the API operation to be called successfully. You can define multiple security requirements; in this case, an application can call your API operation if it satisfies any of the security requirements you have defined.

Any security requirements that you define for an operation completely override any security requirements defined on the parent API. If you do not define any security requirements for an operation, or you delete all security requirements from an operation, the operation inherits the security requirements defined on the parent API. For more information, see Enforcing security requirements on an API.

At any time, you can switch directly to the underlying OpenAPI YAML source by clicking the Source icon OpenAPI Source icon. To return to the design form, click the Form icon Form icon.

Procedure

  1. Open the API for editing, as described in Editing an OpenAPI 3.0 API definition.
  2. Expand Paths, then expand the required Path.
  3. Expand Operations, then expand the required operation.
  4. To create a new security requirement for the operation, complete the following steps:
    1. Click the add icon OpenAPI 3.0 API add icon alongside the Security Requirements entry for the operation in the navigation pane.
    2. Select the security schemes that you want to include in this security requirement. The security schemes listed are those that have been defined in security scheme components; see Defining security scheme components.

      If a selected security scheme is of type OAuth2, select the required scopes; the scopes available for selection are those that were specified in the security scheme component; for more information, see Defining OAuth2 security scheme components.

      If you are applying the OAuth2 security scheme to an API that is enforced by the DataPower API Gateway, you only need select any scopes if Advanced scope check after token generation is not enabled in the native OAuth provider associated with the security scheme. If a default scope has been set in the native OAuth provider and the API request doesn't contain any scope, the default scope is used; for more information, see Configuring scopes for a native OAuth provider.

      Note: The following additional requirement applies to security schemes that will be used with an OAuth third party provider. If you select an OAuth security scheme for protecting a consumer API, you must also include an API key security scheme, as the X-IBM-Client-Id or client_id must be included in the security credentials so that the correct Plan configuration settings can be enforced.
    3. Click Create. The security scheme selections are shown; you can change them again before saving.
    4. Click Submit when done.
  5. To modify an existing security requirement, complete the following steps:
    1. Click the Security entry for the operation in the navigation pane. All previously defined security requirements are listed; the security schemes included in each security requirement are shown.
    2. To change the security schemes for a security requirement, click the edit icon Security requirement edit icon alongside the required security requirement, then change your security requirement selections as required.
    3. Click Submit when done, then click Save.
    4. To delete a security requirement, click the appropriate delete icon Security requirement delete icon, click Delete to confirm, then click Save.
    5. To disable security for the operation, clear the Require one of the following Security Requirements check box, then click Save.
    Note: These settings completely override any security requirements defined on the parent API; see Enforcing security requirements on an API.