Authentication

Introduction

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

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

Authentication Mechanisms

JWT Authentication

JWT Authentication manages the authentication following the JSON Web Token standard.

The token is verified against the configured issuer and audience and according to the specified algorithm.

Supported algorithms are the HMAC256, HMAC384, HMAC512, RSA256, RSA384, RSA512.

For HMAC the key configuration option specifies the secret, for RSA the public key.

auth-mechanisms:
    jwtAuthenticationMechanism:
        enabled: false
        algorithm: HS256
        key: secret
        base64Encoded: false
        usernameClaim: sub
        rolesClaim: roles
        fixedRoles:
    #      - admin
        issuer: myIssuer
        audience: myAudience

Basic Authentication

BasicAuthMechanism manages the Basic Authentication method, where the client credentials are sent via the Authorization request header using the format Authorization: Basic base64(id:pwd). The configuration allows specifying the Authenticator that will be used to verify the credentials.

auth-mechanisms:
    basicAuthMechanism:
        enabled: true
        authenticator: fileRealmAuthenticator

Avoid browsers to open the login popup window

The Basic and Digest Authentication protocols requires responding with a challenge when the request cannot be authenticated as follows:

WWW-Authenticate: Basic realm="RESTHeart Realm"
WWW-Authenticate: Digest realm="RESTHeart Realm",domain="localhost",nonce="Toez71bBUPoNMTU0NDAwNDMzNjEwMXBY+Jp7YX/GVMcxAd61FpY=",opaque="00000000000000000000000000000000",algorithm=MD5,qop="auth"

In browsers this leads to the login popup windows. In our web applications we might want to redirect to a fancy login page when the 401 Unauthorized response code.

To avoid the popup window just add to the request the noauthchallenge query parameter or the header No-Auth-Challenge. This will skip the challenge response.

Digest Authentication

DigestAuthMechanism manages the Digest Authentication method. The configuration allows specifying the Authenticator that will be used to verify the credentials.

auth-mechanisms:
    digestAuthMechanism:
        enabled: true
        realm: RESTHeart Realm
        domain: localhost
        authenticator: fileRealmAuthenticator

Token Authentication

TokenBasicAuthMechanism manages the Basic Authentication method with the actual password replaced by the auth token generated by RESTHeart, i.e. the client credentials are sent via the Authorization request header using the format Authorization: Basic base64(id:auth-token). It requires a Token Manager to be configured (eg. RndTokenManager).

auth-mechanisms:
    tokenBasicAuthMechanism:
        enabled: true

Identity Authentication

IdentityAuthMechanism just authenticates any request building an BaseAccount with the username and roles specified in the configuration. Useful for testing purposes. Note that enabling this causes the DigestAuthMechanism to fail, you cannot use both.

auth-mechanisms:
    identityAuthMechanism:
        enabled: false
        username: admin
        roles:
        - admin
        - user

Watch Authentication mechanisms

Authenticators

Mongo Realm Authenticator

mongoRealAuthenticator authenticates users defined in a MongoDB collection.

Mongo Realm Authenticator is suggested for production usage.

The configuration allows:

• defining the collection to use (users-db and users-collection), the properties of the user document to use as user id, password and roles (prop-id, prop-password and json-path-roles).
• enabling hashed password using the strong bcrypt hashing algorithm (bcrypt-hashed-password and bcrypt-complexity); note that the password is automatically hashed on write requests and that the password property is automatically removed from responses.
• allows initializing the users collection and the admin user if not existing. See create-user option.
• allows controlling the users caching.

authenticators:
    mongoRealmAuthenticator:
        users-db: restheart
        users-collection: users
        prop-id: _id
        prop-password: password
        json-path-roles: $.roles
        bcrypt-hashed-password: true
        bcrypt-complexity: 12
        create-user: true
        create-user-document: '{"_id": "admin", "password": "$2a$12$lZiMMNJ6pkyg4uq/I1cF5uxzUbU25aXHtg7W7sD2ED7DG1wzUoo6u", "roles": ["admin"]}'
        # create-user-document.password must be hashed when bcrypt-hashed-password=true
        # default password is 'secret'
        # see https://bcrypt-generator.com but replace initial '$2y' with '$2a'
        cache-enabled: false
        cache-size: 1000
        cache-ttl: 60000
        cache-expire-policy: AFTER_WRITE

File Realm Authenticator

fileRealmAuthenticator defines users credentials and roles in a simple yml configuration file.

authenticators:
    fileRealmAuthenticator:
        enabled: true
        conf-file: ./etc/users.yml

See users.yml for an example users definition.

Token Managers

Random Token Manager

rndTokenService generates an auth token using a random number generator. It has two arguments, ttl, which is the tokens Time To Live in minutes, and srv-uri the URI of the service that allows to get and invalidate the user auth token.

token-manager:
    rndTokenManager:
        enabled: true
        ttl: 15
        srv-uri: /tokens

Watch Authenticators in RESTHeart