echocat Marquardt is a certificate based distributed authentication / authorization framework.

It uses a central authority which holds the session of a user. The authority produces certificates which are signed using a key pair with a public key trusted by Marquardt services and clients. Certificates have a short time to live of ~ 15 minutes. When they are expired, they must be refreshed.

Clients communicate with the authority to obtain a certificate. They can use the certificate to read the roles of a user to allow access to client features and to get basic user information for presentation. They also use the certificate to access protected services.

Services can authenticate and authorize client requests without roundtrips to the central authority. They read the certificate from the request header and check the requests are also signed by the client (whose public key is contained in the certificate). They use embedded payload from the certificate to access necessary user information.

In order to use Marquardt services, the user must signup at the authority. The signup process is split into two parts, which must be performed sequentially by the client:

• Initialize signup: The client provides their public key and the client id. This will create an empty, temporary user account with status WITHOUT_CREDENTIALS.
• Finalize signup: In this step, the user provides the complete user information and credentials. The data will be added to the temporary user created in the first step and its status will change to CONFIRMED. In case of an additional double-opt in step, the status will change to WITH_CREDENTIALS instead.

This 2-steps allows the authority to perform additional checks or even to have the user call different endpoints (e.g. the confirmation of required legal texts) before finalizing the setup (see checkAdditionalRequirements field in class Authority).

In order to access protected services, a client must obtain a certificate issued by the authority. The following diagram explains the basic process: A client sends its credentials to the authority. The authority checks that the user exists and its credentials are valid, creates a new session if necessary and issues the certificate.

Certificates expire after ~15 minutes and need to be refreshed by the client:

To log out, a client must send its current certificate - also expired ones - to the authority sign out endpoint:

This module contains generic shared classes like custom exceptions and json (de-)serializers. Most notably, this module provides the basic infrastructure for the creation and validation of signatures and certificates.

Signable payload is created by implementing Signable. Deserialization from byte arrays to the object type is performed by implementations of DeserializingFactory. The factory consumes a byte input stream and produces the deserialized signable.

The Signer class is used to create signatures for signables. The Validator is used to both deserialize signables using the respective DeserializingFactory and to verify their signatures.

A certificate is a special case of a signable: It is both a signable itself and also contains a signable as a payload object. In addition, a certificate contains

• the public key of the issuer entity
• the public key of the recipient of the certificate
• an expiry date and
• authorization roles.

Deserialization is performed with CertificateFactory. The deserialization factory of the wrapped payload object (contained in the certificate) can be obtained with getFactoryOfWrapped.

Certificates are transported in a serialized byte format. The authority returns newly issued certificates as a JSON object ( JsonWrappedCertificate ) containing the certificate bytes in the 'certificate' attribute. Clients provide the certificate to the authority and services in an X-Certificate request header. The certificate is always transported Base64 encoded.

[[ VERSION ] [ ISSUER PUBLIC KEY ] [ CLIENT PUBLIC KEY ] [ EXPIRY DATE ] [ ROLES ] [ USER INFO PAYLOAD ]]   [[ AUTHORITY SIGNATURE  ]]

• VERSION - Version of the issued certificate.
• ISSUER PUBLIC KEY - The public key of the authority that issued the certificate
• CLIENT PUBLIC KEY - The public key of the client the certificate is issued for.
• EXPIRY DATE - expiry date of the certificate.
• ROLES - A 64-bit value (Java long) that encodes the user roles as bits.
• USER INFO PAYLOAD - the payload: User information about the client.
• AUTHORITY SIGNATURE - Signature of the authority.

This module contains all code related to the authority, the central entity that all clients must authenticate with and that will issue certificates and manage client sessions.

In order to use the authority, the following interfaces must be implemented:

• Signable - The Signable payload to be included in the certificate. This is usually a subset of the user information or even just the user id or some other identifier.
• User and UserStore - The user object and its persistency store. The user store also provides a method to translate from a user object to the signable certificate payload.
• Session and SessionStore - The server session and its persistency store.

Contains the client interface and a Spring-based implementation. The request signer class can create signatures of the specified request headers. In the Spring implementation it is integrated as part of a HTTP interceptor that adds all required headers (signature and certificate) to the request.

This module provides the required infrastructure to implement a Marquardt-protected service: The CertificateAuthenticationFilter is a servlet filter that extracts the certificate from the X-Certificate request header, deserializes it and validates it. In addition, it validates the http request signature with the client's public key from the certificate. If all validations pass, the filter authenticates the user.

The actual authentication process (e.g. creation of security principals) is left to the implementation. An implementation for Spring Security is provided as SpringSecurityCertificateAuthenticationFilter.

This module is a Spring Boot example application that showcases how to use the different Marquardt components. Start the application by running the ExampleApplication main class.

The example project implements session and user persistence with an H2 database and Spring Data repositories. The REST API of the authority is based on the provided Spring MVC controller.

The class ExampleServiceController implements a simple service API with both protected and unprotected endpoints. For example usage and client calls, see the integration tests of the module: AuthenticationIntegrationTest and ServiceLoginIntegrationTest.

Please activate the provided pre-commit hook to ensure no files without license information are committed. To activate the hook, please run:

cd .git_hooks
./enable_hooks.sh

Development of this project is sponsored by Lautsprecher Teufel GmbH and is used in their Raumfeld products.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.