helidon/docs/shared/security/providers/http-basic-auth.adoc

///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2018, 2020 Oracle and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

=== HTTP Basic Authentication Provider
:description: Helidon Security HTTP Basic Provider
:keywords: helidon, security, basic

HTTP Basic authentication support

==== Setup

[source,xml]
.Maven dependency
----
<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-http-auth</artifactId>
</dependency>
----

[source,text]
.Provider class name
----
io.helidon.security.providers.httpauth.HttpBasicAuthProvider
----

[source,text]
.Provider configuration key
----
http-basic-auth
----

==== Example code
https://github.com/oracle/helidon/tree/master/examples/security/outbound-override[]

[source,yaml]
.Configuration example
----
security:
  providers:
  - http-basic-auth:
      realm: "helidon"
      users:
      - login: "john"
        password: "${CLEAR=password}"
        roles: ["admin"]
      - login: "jack"
        password: "password"
        roles: ["user", "admin"]
      outbound:
        - name: "internal-services"
          hosts: ["*.example.org"]
          # Propagates current user's identity or identity from request property
          outbound-token:
            header: "X-Internal-Auth"
        - name: "partner-service"
          hosts: ["*.partner.org"]
          # Uses this username and password
          username: "partner-user-1"
          password: "${CLEAR=password}"
----

==== Configuration options
The following table shows all configuration options of the provider and their default values

[cols="2,2,5"]

|===
|key |default value |description

|`realm` |`helidon` |The realm shown in challenge when user accesses a service without authentication
|`principal-type` |`USER` |Type of authenticated entity - either `USER` or `SERVICE`, can be used in combination with
                            other authentication mechanism to authenticate both the user (as in person sitting in front of a computer)
                            and a service (as in the application requesting this service on user's behalf)
|`users` |{nbsp} |List of users when using configuration based approach. As an alternative, you can implement a java service (see below).
|`outbound` |{nbsp} |A list of outbound configurations
|`outbound.*.name` |{nbsp} |Required name of outbound configuration
|`outbound.*.username` |{nbsp} |Optional username used for outbound security; if not provided, current identity is propagated
|`outbound.*.password` |{nbsp} |Optional password used for outbound security
|`outbound.*.transports` |any transport |An array of transports this outbound configuration should be used for
|`outbound.*.hosts` |any host |An array of hosts this outbound configuration should be used for, can be a regular expression
|`outbound.*.paths` |any path |An array of paths this outbound configuration should be used for (such as `/greet`), can be a regular expression
|`outbound.*.methods` |any method |An array of HTTP methods this outbound configuration should be used for
|`outbound.*.outbound-token` |`Authorization` header with `basic` prefix |Configuration of outbound header used to propagate
|`outbound.*.outbound-token.header` |{nbsp} |Name of the header used to propagate the token
|`outbound.*.outbound-token.prefix` |{nbsp} |Prefix for the header value, such as `"basic "` (only one of `prefix`, `regexp` and `format` should be defined, `regexp` wins over `prefix`, `format` wins over `regexp`)
|`outbound.*.outbound-token.format` |{nbsp} |String format with a single parameter to create the header value, such as `"basic %1s"`
|`outbound.*.outbound-token.regexp` |{nbsp} |Regular expression to create the header value, such as `"basic (.*)"`
|===

==== How does it work?
See https://tools.ietf.org/html/rfc7617[].

*Authentication of request*

When a request is received without the `Authorization: basic ....` header, a challenge is returned to provide such
authentication.

When a request is received with the `Authorization: basic ....` header, the username and password is validated
against configured users (and users obtained from custom service if any provided).

Subject is created based on the username and roles provided by the user store.

*Identity propagation*

When identity propagation is configured, there are several options for identifying username and password to propagate:

1. We propagate the current username and password (inbound request must be authenticated using basic authentication).
2. We use username and password from an explicitly configured property (See `HttpBasicAuthProvider.EP_PROPERTY_OUTBOUND_USER`
    and `HttpBasicAuthProvider.EP_PROPERTY_OUTBOUND_PASSWORD`)
3. We use username and password associated with an outbound target (see example configuration above)

Identity is propagated only if:

1. There is an outbound target configured for the endpoint
2. Or there is an explicitly configured username/password for the current request (through request property)

*Custom user store*

Java service loader service `io.helidon.security.providers.httpauth.spi.UserStoreService` can be implemented to provide
 users to the provider, such as when validated against an internal database or LDAP server.
The user store is defined so you never need the clear text password of the user.

_Warning on security of HTTP Basic Authenticaton (or lack thereof)_

Basic authentication uses base64 encoded username and password and passes it over the network. Base64 is only encoding,
 not encryption - so anybody that gets hold of the header value can learn the actual username and password of the user.
This is a security risk and an attack vector that everybody should be aware of before using HTTP Basic Authentication.
We recommend using this approach only for testing and demo purposes.