...

This guide assumes that Keycloak is used, see Platform support for the supported OpenID Connect providers. 

Architectural overview

The DCM Maintenance App consists of a frontend and a backend which are served by a single standalone Spring Boot application. The communication between the frontend and backend is going through the Blueriq Gateway Service. 

...

By using the Blueriq Gateway Service, an extra layer of security is added because no token is stored in the frontend and can therefore not be intercepted. This strategy is called the Backend For Fronted (BFF) pattern.

Configuration

To make the authentication and authorization work, you will need to configure an identity provider (Keycloak), The Blueriq Gateway Service and the DCM Maintenance Application itself.

Keycloak

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

...

• A client, specifically for the DCM Maintenance App
  • A client for the Maintenance App frontend
    • Valid origins
      • Here you should list the URLs on which the frontend through the gateway 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 ID token
        • The backend expects the roles to present in the 'roles' claim
    • The scope "roles" should be assigned for the client.
• Users
  • Role mappings for the roles available in the client configured above.

The default login page redirects to Keycloak directly instead of the Gateway service. To make sure it uses the Gateway service as URL to redirect to, change the frontend URL in the Realm settings.

...

blueriq:
  gateway:
    oauth2:
      registration-extensions:
		...
        keycloak:
          end-session-endpoint: http://localhost:9090/keycloak/realms/dcm-maintenance-app/protocol/openid-connect/logout
		...
spring:
  ...
  cloud:
    gateway:
      routes:
        - id: maintenance-app-backend
          uri: http://<maintenance_app_host>:<maintenance_app_port>
          predicates:
            - Path=/dcm-maintenance/**
          filters:
            - PreserveHostHeader
        - id: keycloak
          uri: http://<keycloak_host>:<keycloak_port>
          predicates:
            - Path=/realms/**, /resources/**
          filters:
            - RewriteLocationResponseHeader=AS_IN_REQUEST, Location, ,
            - BackendForFrontend

  security:
    oauth2:
      client:
        provider:
          keycloak-provider:
            client-name: dcm-maintenance-app
            token-uri: http://<keycloak_host>:<keycloak_port>/realms/dcm-maintenance-app/protocol/openid-connect/token
            authorization-uri: http://<keycloak_host>:<keycloak_port>/realms/dcm-maintenance-app/protocol/openid-connect/auth
            jwk-set-uri: http://<keycloak_host>:<keycloak_port>/realms/dcm-maintenance-app/protocol/openid-connect/certs
            user-name-attribute: preferred_username
        registration:
          keycloak:
            provider: keycloak-provider
            scope: openid, profile, email, offline_access, roles
            client-id: dcm-maintenance-development-ui
            authorization-grant-type: authorization_code
            client-secret: <secret>
            redirect-uri: "http://localhost:9090/login/oauth2/code/keycloak"
server:
  port: 9090
...

Maintenance app

For the DCM Maintenance Application to be able to validate the token which will be send to the backend by the Gateway it needs to know the location of the the JSON Web Key set from the identity provider.

This can be done by setting the jwk-set-uri property. You can optionally set the roles-path and the username-path with a JsonPath expression.

...
spring:
  security:
    oauth2:
      resource-server:
        jwt:
          jwk-set-uri: http://<gateway_host>:<gateway_port>/realms/dcm-maintenance-app/protocol/openid-connect/certs   
blueriq:
  jwt:
    roles-path: $.resource_access,.blueriq-runtime,.roles
    username-path: $.preferred_username
...

The jwk-set-uri property cannot be omitted, otherwise Oauth2 will not work. More on this topic can be read here: https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html#oauth2resourceserver-jwt-jwkseturi

Security

The gateway expects to redirect to the identity provider using HTTPS. HTTP is only allowed 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 privileges. 

...

Proxy

If your gateway service or DCM Maintenance App is running behind a proxy, please make sure that requests to the user info endpoint is routed to the gateway:

...