Creating a basic authentication security definition

When you create a basic authentication security definition in an API, you provide details of an LDAP user registry or an authentication URL to be used to authenticate access to the API operations.

About this task

When you use basic authentication, you require API users to provide a valid user name and password to access selected operations. The application developer must also provide an HTTP authorization header in requests that are sent to operations that require basic authentication.

Note: The API Manager UI also includes the ability to create and edit security definitions. However, the preferred method for these tasks is by using the API Designer UI, as described here. Any steps that are specific to a particular UI are marked with an icon.

When you use an authentication URL, the user credentials that are provided in the authorization header are validated by the endpoint specified in the URL. If the user is authenticated, IBM® API Connect expects an authentication URL to return an HTTP 200 OK response status code. All other HTTP response status codes result in an authentication failure and access is denied.

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. For information on applying security definitions, see Applying security definitions to an API.

For more information about using an LDAP user registry for authentication, see LDAP authentication.

Important: If you are using IBM API Connect for IBM Cloud (the SaaS offering), any LDAP registry that you use must be visible on the internet, it must not be accessible only from within your corporate intranet.

Procedure

To create a basic authentication security definition, complete the following steps:

  1. Click APIs.
    The APIs tab opens.
  2. If you have not previously pinned the UI navigation pane then click the Navigate to icon The Navigate to icon.
    The API Manager UI navigation pane opens. To pin the UI navigation pane, click the Pin menu icon The Pin menu icon..
  3. Click Drafts in the UI navigation pane, and then click APIs.
    The APIs tab opens.
  4. To create the security definition in an existing API, click the API you want to work with. To create a new API to add the security definition to, see Creating API definitions.
  5. Navigate to the Security Definitions section.
  6. In the Security Definitions section, click the Add Security Definition icon The add security definition icon..
  7. Select Basic.
    A Basic security definition is added to the Security Definitions section.
  8. Enter a name for the security definition, to replace the default name, and, optionally, a description.
  9. To authenticate users with an authentication URL, complete the following steps:
    1. Select Authentication URL, and specify a URL.
      When establishing authentication, API Connect makes a GET call to your authentication URL. When the call is made, it includes in its authorization header the user name and password it has collected from the user. Confirm that these are correct and respond with an HTTP success code such as 200 OK if you want to allow the application access, or with an HTTP error code such as 401 Unauthorized if you want to deny access.
    2. Icon indicating that this applies only to the API Designer UI To apply a TLS profile, click TLS Profile and enter the name of the required TLS profile.
    3. Icon indicating that this applies only to the API Manager UI To apply a TLS profile, click TLS Profile and select the required TLS profile.
    Note: The TLS profile must be created on the Management server by using the API Manager user interface. For more information, see TLS profiles.
  10. To authenticate users with an LDAP user registry, complete the following steps:
    1. Select User registry.
    2. Icon indicating that this applies only to the API Designer UI Enter the name of the required registry.
    3. Icon indicating that this applies only to the API Manager UI Select the required registry.
    Note: The LDAP user registry must be created on the Management server by using the API Manager user interface. For more information, see Creating an LDAP registry.
  11. Click the Save icon The Save icon. to save your changes.

What to do next

Apply your security definition to the API, or to one or more API operations. For more information, see Applying security definitions to an API and Applying security definitions to an API operation.