Skip to content
SimpleAuthService is designed to be a lightweight user management component for microservice architectures.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



SimpleAuthService is designed to be a lightweight user management component for microservice architectures.

SimpleAuthService provides a REST API to allow users to create and log into accounts, exchanging login credentials (username/password or Facebook tokens) for JSON Web Tokens.

User passwords are hashed using PBKDF2 with SHA512 before storage.


SimpleAuthService requires Tomcat (or similar servlet engine) and optionally a database. There are several ways to deploy the software.


The easiest way to run the software is using the preconfigured docker image.

docker pull bluberrieio/simpleauthservice:latest

Once downloaded, configure the file (see next section) and JWT signing certificates and place them in a folder that is mounted at /etc/sas in the docker image. The Docker container used a MySQL database backend, the configuration details of which are given in the [example file](\ properties.example), and which should not be changed.

For instance, if you place the files in /home/user/sas, you could run SimpleAuthService with the command:

docker run -v /home/user/sas:/etc/sas -p -i -t bluberrieio/simpleauthservice

You can then get the openapi.json specification document to check the service is running with:

curl http://localhost:8080/sas/v1/swagger.json


To deploy the war file to the Java servlet container of your choice. By default, it will use an on disk h2 database. If you would like to use a different RDBMS such as MySQL, create an empty database and user and configure the details in See the next section for more details.

Building from source

You can build the war file yourself from the latest sourcecode using maven with mvn compile war:war.


The service is configured via a Java properties file named, read from one of the following locations:

  • /etc/sas/
  • $HOME/.sas/

An example file can be found in the docs folder.

The following properties should be set to configured the service:

  • redirecturl - the URL email confirmations are redirected to (default value="")
  • sas-user - the preset admin username (default value="")
  • sas-passwd - the preset admin password (default value="changeme")
  • apikey - key used to secure API operations (default value="1234567")
  • jwt-audience - the audience value contained in issued JWT tokens (default value="blahblah")
  • jwt-lifetime - lifetime of issued JWD tokens in miliseconds (default value="86400000")
  • jwt-web-lifetime - lifetime of JWT tokens issued for web logins in miliseconds (default value="43200000")
  • pwd-reset-lifetime - lifetime of password reset tokens in miliseconds (default value="3600000")
  • jwt-refresh-lifetime - lifetime of JWT refresh token (default value="31536000000")
  • jwt-refresh-audience - the audience value contained in issued JWT refresh tokens (default value="sas-renewer")
  • jwt-issuer - the issuer value contained in issued JWT tokens (default value="")
  • facebook-id - Facebook app ID for Facebook login
  • facebook-secret - Facebook app secret for Facebook login
  • publickey - path to public key used to sign JWT tokens
  • privatekey - path to private key used to sign JWT tokens
  • serverurl - URL of running service (e.g. https://localhost/sas/v1)
  • reseturl - the URL of the page to visit to reset a forgotten password.


You can configure SimpleAuthService to send emails to send automated emails to users for the following:

  1. To confirm their email address. When they click on the confirmation link, they are redirected to redirecturl.
  2. When the address is confirmed, a welcome email is sent.
  3. When the user requests to reset their password, a reset email is sent with a link to reseturl.

To configure email sending, the following SMTP server details must be set:

  • email-user - username used to log on to SMTP server
  • email-password - SMTP server password
  • - SMTP server hostname
  • mail.smtp.starttls.enable - SMTP server should use TLS (boolean)
  • mail.smtp.auth - SMTP server requires auth (boolean)

### Database

By default, SimpleAuthService maintains the state of the service to a h2 database file on disk.

SimpleAuthService users Hibernate to map persistent objects to database tables. You can change the backend database used by configuring the following hibernate properties in the file:

  • hibernate.connection.driver_class - database driver to use (default value="org.h2.Driver")
  • hibernate.connection.url - URL of database to use (default value="jdbc:h2:file:/tmp/sas;DB_CLOSE_DELAY=-1;MVCC=TRU")
  • hibernate.connection.username - database username (default value="sa")
  • hibernate.connection.password - database password
  • hibernate.dialect - SQL dialect to use (default value="org.hibernate.dialect.H2Dialect")

Adding other hibernated.* properties to should allow you to override standard hibernate.cfg.xml properties. See the Hibernate documentation for more details.


To generate signed JWT tokens, SimpleAuthService requires the access to the public and private components of a digital certificate.


A Swagger description of the API is available from the service. For example, if the service is deployed on localhost port 80, the Swagger document is available at http://localhost/sas/v1/swagger.json.

A full description of the API is available here.

Operational Notes

A login provides two credentials: a short-lived user JWT token and a longer lived renewal token. The renewal token can be used to renew the user token, without prompting the user for their login credentials.

The renewal token should be stored securely, in a mobile app keystore for example. When used for web logins, the renewal token is not supplied.

It is advisable to deploy the SAS-UI component to configure the service and manage users.

SimpleAuthService supports two user roles:

  1. USER - for everyday users
  2. ADMINISTRATOR - required to access the admin services.

The initial user account (configured in the file) is given the ADMINISTRATOR role, and allowed to grant that role to other users.


Currently, the service can only generate tokens for a single JWT audience.

The tool is designed to be very lightweight and provide the minimum functionality required to run a mobile app or website where the backend is secured with JWT tokens. It does not implement a full OAuth or OpenID flow.


(C) Copyright 2017-2018 Bluberrie Labs (

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.

You can’t perform that action at this time.