// Module included in the following assemblies:
//
// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc

:_mod-docs-content-type: CONCEPT
[id="identity-provider-about-basic-authentication_{context}"]
= About basic authentication

[role="_abstract"]
Configure basic authentication to validate user credentials against a remote service over HTTP. Use this integration when you need a flexible back-end for username and password login in {product-title}.

Basic authentication is a generic back-end integration mechanism that allows users to log in to {product-title} with credentials validated against a remote identity provider.

Because basic authentication is generic, you can use this identity provider for advanced authentication configurations.

[IMPORTANT]
====
Basic authentication must use an HTTPS connection to the remote server to prevent potential snooping of the user ID and password and man-in-the-middle attacks.
====

With basic authentication configured, users send their username and password to {product-title} during login. {product-title} validates those credentials against a remote server. {product-title} makes a server-to-server request, passing the credentials as a basic authentication header.

[NOTE]
====
This only works for username and password login mechanisms, and {product-title} must be able to make network requests to the remote authentication server.
====

Usernames and passwords are validated against a remote URL that is protected by basic authentication and returns JSON.

A `401` response indicates failed authentication.

A non-`200` status, or the presence of a non-empty "error" key, indicates an error:

[source,terminal]
----
{"error":"Error message"}
----

A `200` status with a `sub` (subject) key indicates success:

[source,terminal]
----
{"sub":"userid"}
----

where:

`userid`:: Specifies a value that is unique to the authenticated user and must not be modified.

A successful response can optionally provide additional data, such as:

* A display name using the `name` key. For example:
+
[source,terminal]
----
{"sub":"userid", "name": "User Name", ...}
----
+
* An email address using the `email` key. For example:
+
[source,terminal]
----
{"sub":"userid", "email":"user@example.com", ...}
----
+
* A preferred username using the `preferred_username` key. This is useful when the unique, unchangeable subject is a database key or UID, and a more human-readable name exists. This is used as a hint when provisioning the {product-title} user for the authenticated identity. For example:
+
[source,terminal]
----
{"sub":"014fbff9a07c", "preferred_username":"bob", ...}
----

