SimpleAuthService is designed to be a lightweight user management component for microservice architectures.
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 sas.properties 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 sas.properties file](https://github.com/BluberrieLabs/SimpleAuthService/blob/master/docs/sas.\ 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 127.0.0.1:8080:8080 -i -t bluberrieio/simpleauthservice
You can then get the openapi.json specification document to check the service is running with:
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
sas.properties. 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
sas.properties, read from one of the following locations:
An example sas.properties 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="https://www.google.com")
sas-user- the preset admin username (default value="firstname.lastname@example.org")
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="foo.bar.com")
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:
- To confirm their email address. When they click on the confirmation link, they are redirected to
- When the address is confirmed, a welcome email is sent.
- When the user requests to reset their password, a reset email is sent with a link to
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
mail.smtp.host- SMTP server hostname
mail.smtp.starttls.enable- SMTP server should use TLS (boolean)
mail.smtp.auth- SMTP server requires auth (boolean)
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 sas.properties 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")
hibernated.* properties to sas.properties 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.
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:
- USER - for everyday users
- ADMINISTRATOR - required to access the admin services.
The initial user account (configured in the sas.properties 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 (http://bluberrie.io/).
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.