---
id: web--http-authentification
title: "Http authentication"
summary: "Reads the credentials of a request received by an **Http listener** and passes them on, so the next components can check them. It does not verify anything itself: connect `Output` to the component that checks the credentials (a database lookup, a file, a Script, a **JWT validator**) and raises an error to reject the request. Connect `Input` to the listener's `Authentificate` pin; when this component or one after it raises an error, the listener answers `401` and the request never reaches the listener's `Output` pin."
audience: user
keywords: "input, output, authentificationtype, authparamname, authparamlocation, signatureheadername, timestampheadername, ignoredroutes"
---
# Http authentication

Reads the credentials of a request received by an **Http listener** and passes them on, so the next components can check them. It does not verify anything itself: connect `Output` to the component that checks the credentials (a database lookup, a file, a Script, a **JWT validator**) and raises an error to reject the request. Connect `Input` to the listener's `Authentificate` pin; when this component or one after it raises an error, the listener answers `401` and the request never reaches the listener's `Output` pin.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Input | input | `Viaducta.Plugins.Http.Types.WebHttpRequest` | The incoming request, from the Http listener `Authentificate` pin. |
| Output | output | `Viaducta.Plugins.Http.Types.HttpAuthentificationData` | The credentials found (`Scheme`, `Username`, `Password`, `Token`, `Jwt`, `ApiKey`, `Signature`, `Timestamp`), not verified yet. |

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `AuthentificationType` | dropdown: `0` Basic, `1` Bearer token, `2` JWT, `3` API key, `4` Request signature, `5` Any | `0` | Which credentials to read. |
| `AuthParamName` | string | `ApiKey` | Header, query parameter or cookie that holds the API key (types `3` and `5`). Empty means `ApiKey`. |
| `AuthParamLocation` | dropdown: `1` Header, `2` Query, `3` Cookie | `1` | Where the API key is read from (types `3` and `5`). |
| `SignatureHeaderName` | string | `X-Signature` | Header that holds the request signature (type `4`). |
| `TimestampHeaderName` | string | empty | Optional header that holds the request timestamp (type `4`). When set, the header is required. |
| `IgnoredRoutes` | string | `/login` | Public routes: comma separated paths that need no credentials. |

## Behaviour

- `0` Basic: reads `Authorization: Basic <base64 of username:password>`. The text is split at the first `:`, so passwords may contain colons. Emits `Username` and `Password`.
- `1` Bearer token: reads `Authorization: Bearer <token>`. Emits `Token`.
- `2` JWT: like Bearer, and the token must look like a JWT (dot separated parts). Emits `Jwt`; check it with a **JWT validator**.
- `3` API key: reads the key from the header, query parameter or cookie named `AuthParamName`. Emits `ApiKey`.
- `4` Request signature: reads the signature header and, when configured, the timestamp header. Emits `Signature` and `Timestamp`. Recompute the signature downstream from the request body (`HttpListener` metadata, `Request.Body` or `Request.ByteBody`) with your secret and compare.
- `5` Any: Basic or Bearer from the `Authorization` header when present (a Bearer token that looks like a JWT also fills `Jwt`), otherwise the API key. `Scheme` says which one was found.
- The scheme in the `Authorization` header and all header names are matched without regard to case (HTTP/2 clients send lower case names).
- The `UserInfo` metadata gets `UserName`, `Token` (Bearer or JWT) or `ApiKey`. These are not verified yet.
- Missing or malformed credentials raise a recoverable error with code `401`; the Http listener answers HTTP `401` with a JSON error body. For Basic, Bearer, JWT and Any the answer also carries a `WWW-Authenticate` header, so browsers show their login prompt for Basic.
- When nothing is connected to `Output`, the component shows a warning: the credentials are never checked.

## Public routes

`IgnoredRoutes` lists paths that skip the check, for example `/login,/health,/swagger`. The component then does nothing (no error, no output) and the listener continues normally.

- Only the request path is compared, never the host or the query string, so `/orders?next=/login` is not public.
- A path covers itself and the paths below it: `/login` matches `/login` and `/login/reset`, but not `/loginx` or `/api/login`.
- Matching ignores case and a trailing `/`. Entries containing `?` or `#` are ignored, with a warning when the flow starts.

## Example

```json
{ "AuthentificationType": 2, "IgnoredRoutes": "/login,/health" }
```

Http listener (`Authentificate`) → **Http authentication** → JWT validator