Applying security definitions to an API

The security definition contains security settings that you enforce to define access control requirements for the operations in the API, by applying the security definition to an API.

Before you begin

Create one or more security definitions in your API. For more information, see Creating a security definition.

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.

The following restrictions exist when you apply security definitions to an API:
  • You cannot apply more than two API key security definitions to an API.
  • If you apply an API key security definition for client secret, you must also apply an API key security definition 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 definitions.
  • You can have at most one API key definition 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 definition 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 definition to an API. If you apply a basic security definition, you cannot also apply an OAuth security definition.
  • You can apply at most one OAuth security definition to an API.

Procedure

To apply security definitions to an API, complete the following steps:

  1. In the navigation pane, click Develop icon in the API UI navigation pane Develop, then select the APIs tab.
  2. To apply the definitions to an existing API, click the title of the API that you want to work with.

    To create a new API before you apply the definitions to it, see Creating an API definition.

  3. Navigate to the Security section.
  4. In the Security section, select the security definitions that you want to apply.

    When you apply a security definition to an API, the user interface presents the set of all existing security definitions. You can select one or more of the definitions from the set, to specify the exact combination of definitions that you want this API to satisfy.

    In addition, you can specify multiple combinations of definitions. To specify a second combination, click Add again, and the interface presents a second set of all existing security definitions. Select the check box for each definition that you want included in the second combination. You can add additional sets, and specify additional combinations, until you've created all the valid combinations for the API.

    An application can call your API if it satisfies any of the combinations you have defined.

    Note: The following additional requirement applies to security definitions that will be used with an OAuth third party provider. If you select an OAuth security definition for protecting a consumer API, you must also include an API key security definition, 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.
    The selected definitions are now applied to the API.
  5. If the selected security definition is of type OAuth2, select the required scopes; the scopes available for selection are those that were specified in the security definition; for more information, see Creating an OAuth security definition.
    Note: If you are using the DataPower® Gateway (v5 compatible), you must select at least one scope, and the scope sent in an API request must match one of the selected scopes, otherwise the call fails.

    If you are using 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 definition. 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.

  6. To remove a security definition so that it is no longer applied to the API, clear the selection for that security definition.
  7. Click Save to save your changes.