Adding Authentication

Adding authentication to your applications

Background

Adding Authentication to your applications is beneficial as you can tailor your the functionality to your individual users, and because it provides a way to monitor usage of the different ORN applications.

We provide Keycloak (supported by Red Hat as their 'Red Hat SSO' product) as a Single Sign On (SSO) solution that can easily be deployed into any ORN Virtual Environment and can easily be configured to meet at organisation's needs e.g. to use the organisation's LDAP or Active Directory server for authentication or to delegate out to Authentication Providers such as GitHub, LinkedIn or Google. Once a user is logged in to one application they are automatically logged in to all applications (though access can be restricted based on the user's role as required).

Users are given the standard-user role as default, and checking for this role is usually sufficient unless you need to restrict access to specific users. If so they we can set up additional roles and add specific users to them.

Typical flow

Once you have added authentication to your application this is what typically happens

1. User tries to access your application in a browser
2. The user is detected as not having been authenticated a response is returned to the browser that redirects the browser to the Keycloak login page (along with the URL to return to once authenticated)
3. The user logs in by whatever mechanism(s) is defined in the Keycloak configuration. In the ORN reference site this could by done be delegating to LinkedIn, in which case the user is asked to log in to LinkedIn (if not already logged in) and asked if they want to allow ORN to use this login mechanism. ORN only gets access to minimal information from your LinkedIn login (typically the user's name and email, though this is configurable and the user is told which information is being used).
4. If login is successful then Keycloak returns a response that redirects back to the originally requested page along with and authentication token that contains information about the user and a token that the application can verify to ensure that it does come from Keycloak and is valid.
5. The application can now grant access to the requested page.
6. Following this the browser includes the token in further requests and the application knows that the user is already authenticated.

However in real cases it is not usually the application that handles this, but the application server that the application is running in that does the work. For instance in the case of a Java servlet application running in the Tomcat container it is Tomcat that handles the authentication and then passes the authenticated request to the application. The application itself needs to do nothing. If it wants to use information about the user (e.g. need to know the username) it can do so. e.g. with a servlet it could use the servlet API's HttpServletRequest.getUserPrincipal().

Implementing authentication

The approach needed depends on your type of application. OpenIDConnect and SAML2 are supported and most application servers have documentation for handling these types of authentication.

The Keycloak documentation lists a large number of approaches. You will likely find one that is suitable for your needs.

As and example for automatically doing this as part of deployment see the Squonk app deployment guide.

TODO: provide more examples

Using an sidecar proxy container

If you don't want to handle authentication directly in your deployment you might want to look at using a 'sidecar' container that acts as an authentication proxy as described in the Keycloak documentation. Note: the container image can be found here.

Note: we are yet to test this approach.