Defining API key security schemes

An API key security scheme is used to specify the credentials that an application must provide to identify itself when calling the API operations.

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.

You can require that, when calling an API operation, an application must provide either a client ID, or a client ID and client secret; you create an API key security scheme to specify a credentials requirement. If you require that an application must provide both a client ID and client secret, you must create two API key security schemes, one for each type of credentials.

To make use of an API key security scheme, you must reference it from elsewhere in your API definition. For more information, see Enforcing security requirements on an API and Enforcing security requirements on an operation.

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. If there are already one or more security schemes defined, expand Security Schemes.
  3. To create an API key security scheme, click the add icon OpenAPI 2.0 API add icon alongside Security Schemes, then select apiKey for the Security Definition Type. To edit an API key existing security scheme, click the security scheme name in the navigation pane.
  4. Enter an identifying name of your choice in the Security Scheme Name field.
  5. Specify the parameter name in the Name field.

    If your API is not enforced by the API Connect gateway, enter the parameter name required by your gateway.

    If your API is enforced by the IBM® API Connect gateway, the required value depends on the gateway type setting for the API, as follows:
    • DataPower® API Gateway: For a key of type client secret, you must include the string secret, ignoring case, in the value you specify in the Name field; if the value does not contain the string secret then the key is assumed to be of type client ID.
    • DataPower Gateway (v5 compatible): the value must be as specified in the following table, depending on where the client credentials are located, and the type of credentials.

      Table 1. Client ID and Client secret parameter name values for the DataPower Gateway (v5 compatible)
      Location of credentials Type of credentials Parameter name
      Header Client ID X-IBM-Client-Id
      Header Client secret X-IBM-Client-Secret
      Query Client ID client_id
      Query Client secret client_secret

    When you first create an API, a default API key security definition, of type client ID, is provided.

    For information about including API key parameters in an API call, see Calling an API.
    Note:
    • 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.
    • The client ID and client secret headers that are specified in the request when the API is called are not added automatically to the message context. If you need these headers in the message context for subsequent processing, include a set-variable policy in your API assembly that adds the headers to the message content, taking the values specified in the request; you can do this in either of the following ways:
      • In the Assemble tab, add a Set Variable policy to your API assembly that defines the appropriate actions; for example:
        Table 2.
        Action Set Type Value
        Set message.headers.X-IBM-Client-Id string $(request.headers.X-IBM-Client-Id)
        Set message.headers.X-IBM-Client-Secret string $(request.headers.X-IBM-Client-Secret)
        For more information on configuring a Set Variable policy, see Set Variable.
      • In the Source tab, add a set-variable policy directly to the assembly section in your OpenAPI source; for example:
        assembly:
          execute:
            - set-variable:
                version: 2.0.0
                title: set-variable
                actions:
                  - set: message.headers.X-IBM-Client-Id
                    value: $(request.headers.X-IBM-Client-Id)
                    type: string
                  - set: message.headers.X-IBM-Client-Secret
                    value: $(request.headers.X-IBM-Client-Secret)
                    type: string
        For more information on defining a set-variable policy in your OpenAPI source, see set-variable.
      You should position the set-variable before any policy that needs to access the API key headers; for example, an invoke policy that calls a back-end service that is required to identify the application that made the initial request.
  6. Select the Key Type: client_id or client_secret.
    Important: The client_id is not confidential and functions as a "SecurityScheme" only in the meaning of the OpenAPI specification.

    If you use only the client_id (without the client_secret) as your API Key, be aware that the client_id is not considered a confidential value in the API Manager UI; for example, it might be displayed to other authenticated members of the provider organization. The client_id is treated as a public identifier for apps and cannot be kept private.

    If authentication of the identity of the app calling an API is needed, then the API Key should use both a client_id to identify the app, plus a client_secret to authenticate it. The client_secret is designed to be known only to the app and the authorization server, and it should be protected. IBM API Connect protects the client_secret: it is only available when first generated, it can be stored as a one-way hash to prevent retrieval or leaks, and it can be changed and reset without changing the corresponding client_id. When an API Key is not marked as a client_secret, it will not be protected in the API Manager UI.

  7. Specify whether the credentials are sent in the request header, or as query parameters, by selecting one of the following Located In options:
    header
    The credentials are sent in the request header. This is the default setting.
    query
    The credentials are sent as query parameters. This method is less secure because the client secret could be exposed in a log file.

    The selected option is enforced, and API calls fail if the credentials are included in the wrong location by the caller.

    Note:
    • You must specify the same location for the client ID and client secret, either header or query.
    • If you migrated from API Connect V5, API key security definitions that contain multiple Client ID references, behave differently in Version 10 than in Version 5. For information about the differences, see Client ID behavior in API key security definitions.
  8. Optionally, provide a Description for the security scheme. You can use CommonMark syntax for rich text representation.
  9. If you are creating a new API key security scheme, click Create.
    The security scheme details are displayed for further editing.
  10. Click Save when done.

What to do next

Apply the security scheme to an API or operation. For more information, see Enforcing security requirements on an API and Enforcing security requirements on an operation.