Defining basic authentication security scheme components

A basic authentication security scheme component is used when an application that calls the API is required to authenticate through a user registry.

Before you begin

For authenticating access to the operations of APIs that are enforced on the API Connect gateway, the following user registry types are supported:

Authentication URL
LDAP

The following user registry types are not supported:

OpenID Connect (OIDC)
Local User Registry (LUR)
A custom user registry

Before you can create a basic authentication security definition in an API, the user registry must exist. To create a user registry, you can use either API Manager or Cloud Manager. When you create a registry in API Manager, it is visible only to your provider organization. When you create a registry in Cloud Manager, you can make it visible to multiple provider organizations.

To create a user registry with API Manager, see Working with user registries.

To create a user registry with Cloud Manager, see User registries overview.

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.

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.

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.

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

For information about using an Authentication URL, see Authentication URL user registry.

To make use of a basic authentication security scheme component, 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

Open the API for editing, as described in Editing an OpenAPI 3.0 API definition.
Expand Components then, if there are already one or more security scheme components defined, expand Security Schemes.
To create a basic authentication security scheme component, click the add icon alongside Security Schemes. To edit an existing basic authentication security scheme component, click the component name in the navigation pane.
If you are creating a new basic authentication security scheme component, you can either create it from scratch or you can reference another basic authentication security scheme component.
To create a basic authentication security scheme component from scratch, provide the following information on the Definition tab:
- Security Scheme Name (required): A key that enables this basic authentication security scheme component to be referenced from elsewhere in the API definition; the reference has the following format:
```
#/components/securitySchemes/Security_Scheme_Name
```
- Security Scheme Type (required): Select http.
- Scheme (required): The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.
- Authenticate using User Registry: The name of the user registry to be used for authentication. This is the value of the name field that was auto-generated when the user registry was created.
- Bearer format: A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
- Description: An optional description of the basic authentication security scheme. You can use CommonMark syntax for rich text representation.
To reference another basic authentication security scheme component, provide the following information on the Reference tab:
- Security Scheme Name (required): A key that enables this basic authentication security scheme component to be referenced from elsewhere in the API definition; the reference has the following format:
```
#/components/securitySchemes/Security_Scheme_Name
```
- Reference from: Select a reference to another basic authentication security scheme component.
If you are creating a new basic authentication security scheme component, click Create.
The security scheme component details are displayed for further editing.
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.

Fore more information on LDAP and Authentication URL, see LDAP authentication and Authentication URL user registry.