v9 (current) v8
Edit Page

Authentication

RESTHeart Cloud

Introduction

See Security Overview for a high-level view of the RESTHeart security model.

RESTHeart uses a pluggable architecture. It comes with a strong security implementation that you can easily extend by implementing plugins. This section documents the authentication plugins available out-of-the-box. You can also develop your own.

The three pieces

Authentication is split across three kinds of plugin, and knowing which does what is most of what you need to configure it.

Plugin What it does

Authentication Mechanism

Takes the credentials out of the request. BasicAuthMechanism reads the Authorization: Basic header; JwtAuthenticationMechanism reads a Bearer token. It does not decide whether they are valid.

Authenticator

Verifies those credentials against something — a MongoDB collection, a file, an LDAP server — and builds the account, with its roles. Some mechanisms need none: IdentityAuthMechanism builds the account from configuration alone.

Token Manager

Issues and verifies the auth token a client may use in place of its actual credentials on later requests.

How several mechanisms coexist

More than one mechanism can be enabled. When a request arrives, authenticate() is called on each in turn until one of the following happens:

  • a mechanism authenticates the request, which ends the chain successfully;

  • a mechanism fails the request, which ends the chain with 401 Unauthorized;

  • the list is exhausted, and the request is unauthenticated.

The distinction that matters when combining mechanisms is between declining and failing. A mechanism that finds no credentials of its own shape declines, and the next one gets its turn. A mechanism that finds credentials it recognises but cannot verify fails, and nothing after it runs.

This is why two mechanisms can share one scheme: tokenBasicAuthMechanism reads Authorization: Basic before basicAuthMechanism does and declines what is not one of its tokens, leaving the very same header to be read as a username and password. apiKeyAuthMechanism shares Bearer with the JWT mechanism the same way.

Authentication Mechanisms

Page Mechanisms Credential

JWT

jwtAuthenticationMechanism, plus the JWT Token Manager and the claims RESTHeart reads

Authorization: Bearer <jwt>

Cookie

authCookieSetter, authCookieHandler, authCookieRemover

A Cookie set at login

API Key

apiKeyAuthMechanism and mongoApiKeyAuthenticator — long-lived, revocable keys for CLIs, CI jobs and integrations

Authorization: Bearer <prefixed key>

Basic, Digest, Token and Identity

basicAuthMechanism, digestAuthMechanism, tokenBasicAuthMechanism, identityAuthMechanism

Authorization: Basic, or none at all

Authenticators and Token Managers

Authenticators and Token Managers covers mongoRealmAuthenticator — the one suggested for production — along with fileRealmAuthenticator and rndTokenManager.

Choosing one

  • A browser application wants cookie authentication, so the credential is not reachable from JavaScript.

  • A single-page or mobile application talking to an API wants JWT.

  • A CLI, a CI job or a partner integration wants an API key: long-lived, revocable one at a time, and issuable with fewer roles than the person holding it. It is also the only option when identity is federated, since a user who signed up through OAuth has no password.

  • basicAuthMechanism is the simplest thing that works and is fine behind TLS for server-to-server calls.

See also Client Authentication for how a client carries the credential in practice, and OAuth 2.0 / 2.1 for delegated identity.