Introduction

Aegaeon is an OpenID Connect / OAuth 2.0 server implementation using spring boot. The project was originally inspired by mitreid-connect.

The code is available under Apache 2.0 license and is currently under heavy development.

The project was started with the goal of having a better understanding of Openid / OAuth standard and has evolved to a project with the following goal :

  • Creating an opiniatre implementation. i.e. Having sensible default and being pragmatic.
  • Simple, fast and clean
  • Being up-to-date

Features (completed and planned)

  • Implicit flow (completed)
  • Authorization Code (completed)
  • Client Credential (ongoing)
  • Full error handling (ongoing)
  • User info endpoint (completed)
  • Introspect endpoint (completed)
  • JWT using RSA signature (completed)
  • JWT using HMAC Protection (completed)
  • Clustering ready (ongoing)
  • Basic Client administration
  • API Scopes / Claims centric

Notable Technologies

  • Spring Framework 4.3.10
  • Spring Boot 1.5.6
  • Hibernate 5.0.12
  • Thymeleaf 3.0.7
  • Nimbus 5.1

Installation

Aegaeon is a java app. To run it, you basically need a servlet container. Tomcat, jetty, Wildfly, weblogic (my condolences) or any other should work. Being a Spring Boot application, you can also use boot's embedded server.

Requisites

To run Aegaeon, you will need :

  • A MySQL database
  • A java server (I use tomcat)
  • An HTTP server (I use nginx)

PostgreSQL could probably be used instead of MySQL but is untested currently.

Building Aegaeon

Aegaeon is open source and available under Apache 2.0 license. If you want to build it, grab the source from Github using git :

git clone https://github.com/n4devca/aegaeon.git

After downloading the source, use maven to create a deployable war :

cd aegaeon && mvn -DskipTests package

You will find the war under target directory.

Download prebuild

You can get prebuild release on Github: https://github.com/n4devca/aegaeon/releases.

Setup

Aegaeon Modules

Aegaeon use spring @ConditionalOnProperty annotation to allow you to disable part of the server you may not need.

Features are grouped under different modules. Each module can be controlled by editing spring's boot application.yml or from the command line.

Modules are :

Name Description Default
oauth Openid / OAuth authorization and token endpoint. Enable
login Enable the login page. Enable
information Enable the information endpoints (jwk publishing and server info). Enable
home Enable the home page. Disable
account Enable the user account management. Disable
admin Enable clients and users administration. Disable
introspect Enable the introspect endpoint. Disable

To enable or disable a module using the application.yml, simply fetch the source, open the file src/main/resources/application.yml and set your module to true or false under aegaeon: modules: section.

When completed, rebuild Aegaeon with maven (see Build it).

If prefer to run prebuild war file, building Aegaeon to change a module can be inconvenient. Instead, you may use command line arguments to enable or disable one or more modules.

Beeing a spring's boot application, there are many way to change configuration values at runtime. See here for a complete list : Externalized Configuration - Spring Boot

An example :

Command Line start.sh --aegaeon.modules.login=false

JWT token keys

Following successful authentication and authorization, an openid server create tokens and return these tokens to one of your client to be consume by your resource server. These tokens are usually created using some cryptographic algorithm.

A set of public/private keys is required by Aegaeon to generate these tokens correctly. Future version will include a setup wizard allowing you to create keys automatically but you need to do it by youself currently. Fortunately, there is a convenient project called json-web-key-generator you can use to create your key file.

Please follow these steps (you can rename mykeys.jwks):

clone project git clone https://github.com/mitreid-connect/json-web-key-generator.git

compile sources cd json-web-key-generator && mvn -DskipTests package

create keys cd target java -jar json-web-key-generator-0.4-SNAPSHOT-jar-with-dependencies.jar -i HMAC -t oct -s 512 -S -o mykeys.jwks java -jar json-web-key-generator-0.4-SNAPSHOT-jar-with-dependencies.jar -i RSA -t RSA -s 2048 -S -o mykeys.jwks

Move the jwks file to another folder and note the path.