Introduction
Authentication Mechanisms
Authenticators
- Mongo Realm Authenticator
- File Realm Authenticator
Token Managers
- Random Token Manager
- JWT Token Manager

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. If you want to disable checking issuer or audience, set them to null. The property audience can be null, a String or an array of Strings.

The authenticated client will gain the roles included in the JWT claim set by rolesClaim or the roles specified by the configuration option fixedRoles. It’s not possible to set both rolesClaim and fixedRoles

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

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

jwtAuthenticationMechanism:
    enabled: true
    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.

basicAuthMechanism:
    enabled: true
    authenticator: fileRealmAuthenticator

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.

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).

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.

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

Tip	Watch Authentication mechanisms

Authenticators

Mongo Realm Authenticator

mongoRealAuthenticator authenticates users defined in a MongoDB collection.

Note	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.

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
    enforce-minimum-password-strenght: false
    # Integer from 0 to 4
    # 0 Weak        （guesses < 3^10）
    # 1 Fair        （guesses < 6^10）
    # 2 Good        （guesses < 8^10）
    # 3 Strong      （guesses < 10^10）
    # 4 Very strong （guesses >= 10^10）
    minimum-password-strength: 3

File Realm Authenticator

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

fileRealmAuthenticator:
    enabled: true
    #conf-file: ./etc/users.yml
    users:
    - userid: admin
      password: null
      roles: [admin]

The conf-file path is either absolute, or relative to the restheart configuration file (if specified) or relative to the plugins directory (if using the default configuration).

See users.yml for an example users definition.

Note	defining users directly in the configuration rather than on a separate `users.yml` file is available from RESTHeart v7.2

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.

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

JWT Token Manager

jwtTokenManager An implementation of Token Manger that issues and verifies auth tokens in a cluster compatible way.

Each token can be verified by any node of the cluster regardless which one actually issued it (as long as they share the same secret)

jwtTokenManager:
    key: secret
    enabled: true
    ttl: 15
    srv-uri: /tokens
    issuer: restheart.com

The query parameter renew-auth-token forces the token to be renewed.

Generating a new token is a cryptographic operation, and it can have a significant performance overhead. It is responsibility of the client to renew the token using this query parameter when it is going to expiry somehow soon.

Tip	Watch Authenticators in RESTHeart