You are viewing the documentation for Blueriq 16. Documentation for other versions is available in our documentation directory.
The DCM Maintenance App uses OAuth2 for authentication and authorization in combination with the Blueriq Gateway Service and an OAuth provider which acts as the identity provider.
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.
This is the way the DCM Maintenance App is setup when installed with the Blueriq installer. The Blueriq Gateway Service and Keycloak are separate components. The Blueriq Gateway Service acts as an "OAuth client" and the Backend 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.
Instead of directly interacting with the Frontend, the Gateway serves the Frontend to the user. The Frontend is not initially aware where Keycloak or any other data to display is located.
Therefore the Frontend asks the Backend (through the Gateway) for this data. The Gateway first validates if the user has an active authenticated session, and redirects to Keycloak when this is not the case.
Keycloak then handles the entire login flow and when a user has successfully logged in, it redirects back to the Gateway which then redirects to the Frontend where the session cookie is set. This session is used with every subsequent API call to the Gateway.
The Gateway first validates that a token belongs to this session. Then the token is send with the requested API Call to the Backend where 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 Gateway with the requested data which then get send to the Frontend.
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.
The following things should be configured in 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
- The roles that are used in the application
- 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
- A mapper that specifies how the roles are translated into the ID token
- The scope "roles" should be assigned for the client.
- Valid origins
- A client for the Maintenance App frontend
- 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.
Tip
In Keycloak, you can see the id-tokens via clients → <client> → clients-scopes → evaluate → <user>. This could be helpful for debugging purposes.
For more information, please refer to: https://openid.net/connect/ and https://www.keycloak.org/.
An example realm export can be found here:
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.
The following roles are known by the application and can be assigned to a user:
Role | Permission |
---|---|
guest | view-data |
maintainer | view-sensitive-data |
owner | view-sensitive-data mutate-data |
auditor | No privileges mapped. Only audit functionality is available |
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:
Permission | Description |
---|---|
view-data | Allows read-only access to non-sensitive data |
view-sensitive-data | Allows read-only access to all data including:
|
mutate-data | Allows executing actions that mutate data |
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:
location /userInfo { proxy_pass http://gateway; }