Instead of using the basic authentication mechanism of the maintenance app, it is also possible to setup authentication and authorization with OAuth.

To enable OAuth you have to configure the maintenance app to use OAuth instead of basic authentication and an OAuth provider to act as the identity provider for the maintenance application. This guide assumes that you use Keycloak, although any other OAuth providers should also work.

Architectural overview

In this scenario, both the front- and backend are served by a single standalone spring boot application. This is the way the dcm maintenance app is setup when installed with the Blueriq installer. Keycloak is a separate component an can be run anywhere. The frontend acts as an "OAuth client" and the backend (or API) acts as a "resource server". Keycloak is used as an identity provider and as such handles the task of authenticating the user. 

The diagram below describes the flow that a user goes through when first accessing the dcm maintenance application.

Because configuration such as the authentication method (Basic or OAuth) and in the case of OAuth also the location of keycloak and the redirect url, are only known at deploy-time. Therefore the frontend first calls de backend to ask for this data.  The frontend redirects to keycloak based on the url configured in the backend.

Keycloak then handles the entire login flow and when a user has successfully logged in, redirects back to the frontend application with an authentication token. This token is then sent to the backend with each subsequent api call.

The token is first verified by the backend itself and later also with keycloak. More on what happens on the backend can be found here: https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html#_runtime_expectations

Only after these steps have succeeded, the backend will respond to the frontend with the requested data. 

Configuration

To configure the dcm maintenance application for OAuth, take the following steps. 

Keycloak

This guide assumes that you already  have admin access to a running instance of keycloak. 

The following things should be configured in keycloak:

• A realm (specific) for the dcm maintenance app
  • A client for the maintenance app frontend
    • Valid origins
      • Here you should list the urls on which the frontend is accessible 
    • Valid redirect urls 
      • Here you should list the urls that can be used to redirect to after successfully logging in with keycloak
    • Roles
      • The roles that are used in the application
        • see the Authorization section for more information
    • RoleMapper
      • A mapper that specifies how the roles are translated into the token
        • The backend expects the roles to present in the 'roles' claim
• Users
  • Role mappings for the roles available in the client configured above.

For more information, please refer to: https://openid.net/connect/ and https://www.keycloak.org/.

An example realm export can be found here: 

dcm-maintenance-app-realm-export.json

Maintenance app:

For the maintenance app you need to configure the  blueriq-dcm-maintenance-app.yml to enable OAuth. 

First configure the maintenance app as an OAuth resource server:

...
spring:
  security:
    oauth2:
      resource-server:
        jwt:
          issuer-uri: http://localhost:18087/realms/dcm-maintenance-app
          jwk-set-uri: http://localhost:18087/realms/dcm-maintenance-app/protocol/openid-connect/certs   
...

The issuer-uri should point to your keycloak instance and the realm you've configured earlier. 

The jwk-set-uri can be omitted, but in that case the identity provider should be up and running before you start the maintenance app. More on this topic can be read here: https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html#oauth2resourceserver-jwt-jwkseturi

...
blueriq:
  dcm:
    maintenance:
      app:
        oauth:
           clientId: 'dcm-maintenance-development-ui' 
           redirectUri: 'http://localhost:8080/dcm-maintenance'

...

The clientId should match the name of the client configured in Keycloak. Make sure the client access type is set to public in Keycloak.

The redirectUri should point to a location where the frontend can be reached. This uri should als be configured in keycloak under the valid redirect uris.

Security

The frontend expects to redirect to the identity provider using https. The only way http is allowed is when the host is localhost.

Authorization 

In the maintenance app a role base access control system is implemented. This means that a user has a certain role and with a role come one or more priviliges. 

The following roles are known by the application and can be assigned to a user:

The only thing to configure is one (or more) of the roles described above. The roles are translated into permission by the maintenance application, they determine what a user can do in the application.

The following permissions are known: