Enforcing security requirements on an API

To enforce security requirements on an API, you apply previously created security schemes that specify various aspects of API security configuration.

About this task

Note: This task relates to configuring an OpenAPI 2.0 API definition. For details on how to configure an OpenAPI 3.0 API definition, see Editing an OpenAPI 3.0 API definition.

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 definitions, see Defining security schemes.

The following restrictions exist when you apply security schemes to an API:
  • You cannot apply more than two API key security schemes to an API.
  • If you apply an API key security scheme for client secret, you must also apply an API key security scheme for client ID.
  • If you require the application developer to supply both client ID and client secret, you must apply two separate API key security schemes.
  • You can have at most one API key scheme of type client ID, regardless of whether the client ID is sent in the request header or as a query parameter.
  • You can have at most one API key scheme of type client secret, regardless of whether the client secret is sent in the request header or as a query parameter.
  • You cannot apply more than one basic security scheme to an API. If you apply a basic security scheme, you cannot also apply an OAuth security scheme.
  • You can apply at most one OAuth security scheme to an API.

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

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 2.0 API definition.
  2. Expand General.
  3. To create a new security requirement for the API, complete the following steps:
    1. Click the add icon OpenAPI 2.0 API add icon alongside Security 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; see Defining security schemes.

      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; for more information, see Defining OAuth2 security schemes.

      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.
  4. To modify an existing security requirement, complete the following steps:
    1. Click Security 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 API, clear the Require one of the following Security Requirements check box, then click Save.