This is a pax web whiteboard extender webapp that serves as authenticator and login page for the nginx_auth_request_module

Steinar Bang 47f4e939d1 Use JSoup to set error message on the login.html page returned by login POST submit, instead of having one static HTML page per error message 3 days ago
authservice.db.derby.test 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago
authservice.db.liquibase 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago
authservice.db.postgresql 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago
authservice.definitions 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago
authservice.tests 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago
authservice.users 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago
authservice.web.security 47f4e939d1 Use JSoup to set error message on the login.html page returned by login POST submit, instead of having one static HTML page per error message 3 days ago
authservice.web.security.dbrealm 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago
authservice.web.security.memorysession 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago
authservice.web.users.api 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago
authservice.web.users.frontend 2333ab76ac Allow reload of the permissions modify and permission add pages 4 days ago
src 206e55f225 Create a feature that loads authservice and user-admin without requiring a database 3 weeks ago
.editorconfig cfeea2849c Initial commit. 1 year ago
.gitignore cfeea2849c Initial commit. 1 year ago
.travis.yml 0cca0fa221 Use maven batch mode on travis-ci builds to avoid control character output in the console 1 week ago
LICENSE 10b035d97f License this software under Apache License v 2.0. 1 year ago
README.org dd3854a529 Replace ${project.version} with 1.0.2 in maven URL for the authservice feature repository in example in the README 1 week ago
pom.xml 6089737801 [maven-release-plugin] prepare for next development iteration 1 week ago

README.org

Forms based nginx login and pluggable shiro auth in karaf

My usecase was this: I had a set of small OSGi web whiteboard web applications running in apache karaf fronted by nginx and I wanted to have the same login and set of users across all web application, and I wanted to have the same forms based for nginx as well. A sort of "poor man's single signon".

This project was my solution.

    This project contains a set of [[https://karaf.apache.org/manual/latest/#_feature_and_resolver][apache karaf features]] that fills two purposes
  1. Providing a forms based login mechanism for nginx (Note: the webapp provides only authentication. No authorization of individual URLs. All authenticated users get in)
  2. Providing a "poor man's single sign-on" for web applications running in the same apache karaf instance

Status of the project

file:https://travis-ci.org/steinarb/authservice.svg?branch=master file:https://coveralls.io/repos/steinarb/authservice/badge.svg file:https://sonarcloud.io/api/project_badges/measure?project=no.priv.bang.authservice%3Aauthservice&metric=alert_status#.svg file:https://maven-badges.herokuapp.com/maven-central/no.priv.bang.authservice/authservice/badge.svg file:https://www.javadoc.io/badge/no.priv.bang.authservice/authservice.svg

SonarCloud

file:https://sonarcloud.io/api/project_badges/measure?project=no.priv.bang.authservice%3Aauthservice&metric=ncloc#.svg file:https://sonarcloud.io/api/project_badges/measure?project=no.priv.bang.authservice%3Aauthservice&metric=bugs#.svg file:https://sonarcloud.io/api/project_badges/measure?project=no.priv.bang.authservice%3Aauthservice&metric=vulnerabilities#.svg file:https://sonarcloud.io/api/project_badges/measure?project=no.priv.bang.authservice%3Aauthservice&metric=code_smells#.svg file:https://sonarcloud.io/api/project_badges/measure?project=no.priv.bang.authservice%3Aauthservice&metric=coverage#.svg

Installing on karaf

/Note/: The instructions here don't describe a production enviroment, but they describe setting up something that will let the service be startet.

The webapp needs PostgreSQL running, with a database named "ukelonn" containing the table users, and a no-password authentication scheme.

    Instructions:
  1. In bash, clone and build the authservice app:
  2. #+BEGIN_EXAMPLE mkdir -p ~/git/ cd ~/git/ git clone https://github.com/steinarb/authservice.git cd ~/git/authservice/ mvn clean install #+END_EXAMPLE
  3. [https://karaf.apache.org/manual/latest/quick-start.html][Follow the quick start guide to downloading, unpacking and starting apache karaf]]
  4. In the karaf shell, install the authservice feature repository
  5. #+BEGIN_EXAMPLE feature:repo-add mvn:no.priv.bang.authservice/authservice/LATEST/xml/features #+END_EXAMPLE
  6. In the karaf shell, install the feature that installs the authorization service that is used by nginx (this feature installs a set of test users, roles and features)
  7. #+BEGIN_EXAMPLE feature:install authservice-with-derby-dbrealm-and-session #+END_EXAMPLE
  8. Open a browser on the URL http://localhost:8181/authservice and do a login with a valid username/password combination (e.g. "admin/admin")
  9. Open a browser on the URL http://localhost:8181/authservice/check and verify that it doesn't return a 401 HTTP code
  10. Optionally install the user administration UI (not needed for using this service with nginx, but needed for administrating the access)
  11. #+BEGIN_EXAMPLE feature:install user-admin-with-derby #+END_EXAMPLE
  12. Open a browser on the URL http://localhost:8181/authservice/useradmin and test adding/modifying users, roles and permissions

Forms based login for nginx

    The webapp installed by the above installation instructions offers two URLs for use by the [[http://nginx.org/en/docs/http/ngx_http_auth_request_module.html][NGINX auth_request module]]:
  • /auth which will just check the login state of Apache Shiro, returning the status code 401 for failure and 200 for success
  • /login which contains a login form and will authenticate against Apache Shiro

The webapp is implemented as two servlets exposed as OSGi services, that will be picked up by the pax web whiteboard extender.

Installing and configuring nginx

    Instructions:
  1. Install nginx with the auth module. On debian this is done with the command
  2. #+BEGIN_EXAMPLE apt-get update apt-get install nginx-extras #+END_EXAMPLE
  3. Add the following to the /etc/nginx/sites-available/default (adapt this to the actual server/site in use):
  4. #+BEGIN_SRC conf server { listen 80 default_server; listen [::]:80 default_server;

root /var/www/html;

# Add index.php to the list if you are using PHP index index.html index.htm index.nginx-debian.html;

server_name _;

location /authservice { auth_request off; # Necessary for REST API POST to work, shiro will handle authorization here proxy_pass http://localhost:8181/authservice; proxy_cookie_path ~^/authservice.*$ /; proxy_set_header Host $host; }

# Avoid browser attempt at fetching favicon.ico triggering a login and redirecting # a 404 Not Found when there is no favicon.ico on the site (which is perferctly OK # for both the site and the browser) location /favicon.ico { auth_request off; }

location / { # First attempt to serve request as file, then # as directory, then fall back to displaying a 404. try_files $uri $uri/ =404; }

# Auth configuration auth_request /authservice/check; error_page 401 = @error401;

Installing and configuring postgresql

Installing and configuring apache karaf

Integrating with a Declarative Services (DS) web whiteboard application in karaf

    # If the user is not logged in, redirect to authservice login URL, with redirect information location @error401 { add_header X-Original-URI "$scheme://$http_host$request_uri"; add_header Set-Cookie "NSREDIRECT=$scheme://$http_host$request_uri"; return 302 /authservice/login } } #+END_SRC /Note/: only command examples for debian/ubuntu/etc. are shown, but the overall steps should work on a lot of platforms
  1. Install PostgreSQL, as root do the following command:
  2. #+BEGIN_EXAMPLE apt-get install postgresql #+END_EXAMPLE
  3. Add a PostgreSQL user named "karaf", as root do the following command
  4. #+BEGIN_EXAMPLE PGPASSWORD=karaf sudo -u postgres createuser karaf #+END_EXAMPLE /Note/: Replace the password in the PGPASSWORD environment variable with something other than the example and use that password in the karaf configuration
  5. Create an empty PostgreSQL database named "authservice" owned by user "karaf"
  6. #+BEGIN_EXAMPLE sudo -u postgres createdb -O karaf authservice #+END_EXAMPLE Instructions:
  7. Install apache karaf as a service, either using the karaf installation scripts or by using apt-get and the unofficial karaf deb package
  8. SSH in to the karaf console:
  9. #+BEGIN_EXAMPLE ssh -p 8101 karaf@localhost #+END_EXAMPLE The default password is "karaf" (without the quotes). It might be a good idea to change this. See the karaf documentation for how to change the password
  10. In the karaf console, do the following:
  11. Add connection configuration for the postgresql database:
  12. #+BEGIN_EXAMPLE config:edit no.priv.bang.authservice.db.postgresql.PostgresqlDatabase config:property-set authservice.db.jdbc.url "jdbc:postgresql:///authservice" config:property-set authservice.db.jdbc.user "karaf" config:property-set authservice.db.jdbc.password "karaf" config:update #+END_EXAMPLE /Note/: use the actual password given in the PGPASSWORD environment variable when creating the karaf user
  13. Install authservice from maven central:
  14. #+BEGIN_EXAMPLE feature:repo-add mvn:no.priv.bang.authservice/authservice/LATEST/xml/features feature:install user-admin-with-postgresql #+END_EXAMPLE
  15. Open a the nginx authservice URL in a web browser, e.g. https://myserver.com/authservice/ and:
  16. Log in as user "admin" with password "admin" (without the quotes)
  17. Click on the "User administration UI" link
  18. In the administration UI:
  19. Click on "Administrate users"
  20. Change the password of user "admin"
  21. Add users that are to be able to log in to nginx
  22. /Note/: The nginx config provides only authentication for nginx, no authorization based on the combination of path and role or permission. Therefore there is no need to add roles to users that only needs to log in Users that need to administrate other users, should get the useradmin role
  23. Add some links to the selfservice URLs from your website's top page (or whereever is convenient):
  24. Change password: https://myserver.com/authservice/password/
  25. Modify real namd and email: https://myserver.com/authservice/user
  26. /Note/: only command examples for debian/ubuntu/etc. are shown, but the overall steps should work on a lot of platforms
    Do the following steps:
  1. Install PostgreSQL, as root do the following command:
  2. #+BEGIN_EXAMPLE apt-get install postgresql #+END_EXAMPLE
  3. Add a PostgreSQL user named "karaf", as root do the following command
  4. #+BEGIN_EXAMPLE PGPASSWORD=karaf sudo -u postgres createuser karaf #+END_EXAMPLE /Note/: Replace the password in the PGPASSWORD environment variable with something other than the example and use that password in the karaf configuration
  5. Create an empty PostgreSQL database named "authservice" owned by user "karaf"
  6. #+BEGIN_EXAMPLE sudo -u postgres createdb -O karaf authservice #+END_EXAMPLE
  7. SSH into the karaf console and add connection configuration for the postgresql database with the following commands:
  8. #+BEGIN_EXAMPLE config:edit no.priv.bang.authservice.db.postgresql.PostgresqlDatabase config:property-set authservice.db.jdbc.url "jdbc:postgresql:///authservice" config:property-set authservice.db.jdbc.user "karaf" config:property-set authservice.db.jdbc.password "karaf" config:update #+END_EXAMPLE /Note/: use the actual password given in the PGPASSWORD environment variable when creating the karaf user
  9. Create a new DS component maven project, containing
  10. A src/main/feature/feature.xml template file, referencing the authservice feature repository and the authservice feature, e.g.:
  11. #+BEGIN_SRC nxml mvn:no.priv.bang.authservice/authservice/1.0.2/xml/features user-admin-with-postgresql #+END_SRC
  12. Add a shiro compile time dependency to the project's maven dependencies:
  13. #+BEGIN_EXAMPLE org.apache.shiro shiro-core 1.3.2 provided #+END_EXAMPLE
  14. A DS component exposing a ServletContextHelper service to the web whiteboard, e.g.:
  15. #+BEGIN_SRC java @Component( property= { HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_NAME+"=ukelonn", HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_PATH+"=/ukelonn"}, service=ServletContextHelper.class, immediate=true ) public class UkelonnServletContextHelper extends ServletContextHelper { } #+END_SRC
  16. A DS component exposing a Filter service to the web whiteboard, extending the AbstractShiroFilter, requiring shiro Realm and SessionDAO OSGi service injections, and configured using code (the shiro.ini mechanism doesn't work well in OSGi), eg.:
  17. #+BEGIN_SRC java @Component( property= { HttpWhiteboardConstants.HTTP_WHITEBOARD_FILTER_PATTERN+"=/*", HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_SELECT + "=(" + HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_NAME +"=ukelonn)", "servletNames=ukelonn"}, service=Filter.class, immediate=true ) public class UkelonnShiroFilter extends AbstractShiroFilter { // NOSONAR

private Realm realm; private SessionDAO session; private static final Ini INI_FILE = new Ini(); static { // Can't use the Ini.fromResourcePath(String) method because it can't find "shiro.ini" on the classpath in an OSGi context INI_FILE.load(UkelonnShiroFilter.class.getClassLoader().getResourceAsStream("shiro.ini")); }

@Reference public void setRealm(Realm realm) { this.realm = realm; }

@Reference public void setSession(SessionDAO session) { this.session = session; }

@Activate public void activate() { WebIniSecurityManagerFactory securityManagerFactory = new WebIniSecurityManagerFactory(INI_FILE); DefaultWebSecurityManager securityManager = (DefaultWebSecurityManager) securityManagerFactory.createInstance(); DefaultWebSessionManager sessionmanager = new DefaultWebSessionManager(); sessionmanager.setSessionDAO(session); securityManager.setSessionManager(sessionmanager); setSecurityManager(securityManager); securityManager.setRealm(realm);

    IniFilterChainResolverFactory filterChainResolverFactory = new IniFilterChainResolverFactory(INI_FILE, securityManagerFactory.getBeans()); FilterChainResolver resolver = filterChainResolverFactory.createInstance(); setFilterChainResolver(resolver); } } #+END_SRC
  1. A shiro.ini resource containing a [urls] section providing access to various path, e.g:
  2. #+BEGIN_EXAMPLE [main] authc.loginUrl = /login

[users]

    [urls] / = authc /user* = user /admin/** = roles[administrator] /api/login = anon /api/registerpayment = roles[administrator] /api/job/update = roles[administrator] /api/admin/** = roles[administrator] /api/** = authc /performedjobs = authc /performedpayments = authc #+END_EXAMPLE
  1. Something listening to the /login path inside the context provided by the WebContextHelper (i.e. /ukelonn/login in this example) and handling login. "Something" could be a servlet or a JAX-RS resource. An example of a JAX-RS resource to handle login, is this resource, which when receiving a GET returns an HTML page with a login form, and on receiving a POST from the form, performs the login:
  2. #+BEGIN_SRC java @Path("") public class LoginResource {

@GET @Path("/login") @Produces(MediaType.TEXT_HTML) public InputStream getLogin() { return getClass().getClassLoader().getResourceAsStream("web/login.html"); }

@POST @Path("/login") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces("text/html") public Response postLogin(@FormParam("username") String username, @FormParam("password") String password) { Subject subject = SecurityUtils.getSubject();

UsernamePasswordToken token = new UsernamePasswordToken(username, password.toCharArray(), true); try { subject.login(token);

return Response.status(Response.Status.FOUND).entity("Login successful!").build(); } catch(UnknownAccountException e) { return Response.status(Response.Status.UNAUTHORIZED).entity("Unknown account")).build(); } catch (IncorrectCredentialsException e) { return Response.status(Response.Status.UNAUTHORIZED).entity("Wrong password")).build(); } catch (LockedAccountException e) { return Response.status(Response.Status.UNAUTHORIZED).entity("Account is locked")).build(); } catch (AuthenticationException e) { return Response.status(Response.Status.UNAUTHORIZED).entity("Unable to log in")).build(); } catch (Exception e) { throw new InternalServerErrorException(); } finally { token.clear(); } } } #+END_SRC Note! if the user logs in via the login form on the authservice path on the same karaf server, the user will be logged into your application as well.

Various ways of integrating with other webapps in karaf

    There are several ways for a webapp to interact with authservice:
  1. Install authservice separately and add OSGi service injections for shiro Realm and Session (all user administration done in the authservice webapplication)
  2. Add the features for the liquibase database setup and the shiro Realm and Session and provide the necessary tables from a different web application's database
  3. Add the features for the authservice UserManagementService implementation, as well as the features for Realm and Session and and implement a user management GUI and webservice on top of the UserManagementService

...or various permutations of the above. With ukelonn I plan to add the authservice tables to the ukelonn database, and then let the ukelonn database provide the database for authservice itself. I have made a first step in the direction of authservice integration by basing ukelonn's user management on the UserManagementService OSGi service, so that it later can be replaced by the authservice implementation of the service.

Integrating with other databases than PostgreSQL

Short story: it should be possible. It should possible to use blank JDBC database that can be connected to with a combination of a JDBC url and username and password.

    Possible approach:
  1. Copy the authservice postgresql maven project
  2. Remove the postgresql compile scope dependency from the pom.xml (this dependency adds a bundle dependency to the feature file)
  3. Add a dependency to the desired JDBC driver. It has to be something that provides a DataSourceFactory OSGi service. If the database system's JDBC driver doesn't provide a DataSourceFactory OSGi service (like e.g. PostgreSQL does), check if the pax-jdbc project have something appropriate

Release history

Date Version Comment
[2019-04-15] 1.0.2 Upgrade apache shiro from version 1.3.1 to version 1.3.2
[2019-04-12] 1.0.1 Avoid constraint name conflict caused by copy-paste from ukelonn liquibase schema, fix aggregate javadoc, ensure user admin with role useradmin is always created if not present
[2019-04-02] 1.0.0 Initial release

License

This software is licensed under Apache Public License v 2.0.

See the LICENSE file for the full details.