Installation

The Gateway Service is a standalone application. The corresponding JAR file can be found in the release zip or in Artifactory: https://artifactory.blueriq.com/artifactory/libs-release/com/blueriq/blueriq-gateway-service/. The application requires a config location to specify the configuration outlined below. Note that the Blueriq DCM Development Installation includes the Gateway Service including configuration.

System requirements

Minimal

2 CPU cores
256 MB Heap

Recommended

2 CPU cores
512 MB Heap

Third party tools

Keycloak

The Gateway Service uses an OpenId Connect Provider such as Keycloak to authenticate requests with. To find out the supported version of Keycloak, please visit the Current platform support page. The Gateway Service should be able to connect to the Keycloak instance.

Ideally, Keycloak runs on its own dedicated server, with sufficient resources. We refer to the website of Keycloak for advice on hardware requirements.

Redis (optional)

The Gateway Service optionally uses a Redis key-value store to offload session state. This feature needs to be enabled if you want the Gateway Service to work in a multi-node setup.

To find out the supported version of Redis, please visit the Current platform support page. The Gateway Service should be able to connect to the Redis instance. How to configure this feature is in the "External Session Configuration" part of this page.

Ideally, Redis runs on its own dedicated server, with sufficient resources. We refer to the website of Redis for advice on hardware requirements.

Features

Routing

The main feature of the Gateway Service is for it to be a gateway between your front facing applications and your APIs. This is done by configuring routes in the Gateway Service. These routes are essentially path mappings between requests and APIs.

Backend For Frontend (BFF)

One of the features of the Gateway Service is to let it act as a Backend For Frontend. By doing so we ensure you that security tokens are not sent to your front facing application, but rather stay behind the Gateway itself. As security tokens in front facing applications tend have a security risk we mitigate that by only sending a Secure Session Cookie to front facing applications. To let the Gateway service act a BFF, additional configuration and an OpenID Connect Identity Provider, such as Keycloak, are required.

The diagram below describes the flow that a user goes through when first accessing the authenticated resources through the Gateway Service.

Token management

The Blueriq Gateway Service automatically manages access tokens by refreshing them when required. The validity of access tokens and refresh tokens can be configured in the Identity Provider. For Keycloak, this can be done on the Tokens tab in the Realm Settings. The access token can be configured using the Access Token Lifespan setting. The refresh token validity is equal to the smallest value among the SSO Session Idle, Client Session Idle, SSO Session Max, and Client Session Max settings on the same tab. For more information on these settings, please refer to the Keycloak documentation.

Single Sign On

Starting with version 0.4.0 the Blueriq Gateway Service supports Single Sign On. To support Single Sign On, we have made some changes to the gateway so that Keycloak does not have to be configured to run to a Reverse Proxy and the Blueriq Gateway Service. This make it possible to use existing Keycloak session from other applications and therefor support Single Sign On.

In the diagram above the User navigates to Application X using the appX.com. Application X authenticates with Keycloak trough the Gateway, seeing that user is not already authorized with Keycloak it will request the user to login with Keycloak. Now that the user is authenticated and the user navigates to Application Y using appY.com, the Gateway and Keycloak will realize that the user is already authenticated and does not need to perform a login.

Configuration

Keycloak

Configuration

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

The following things should be configured in Keycloak:

• A realm
  • A client for the Gateway service
    • 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
    • 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.

The default login page redirects to Keycloak directly instead of the Gateway service. When running the Gateway service without an NGINX proxy in front of it, make sure to change the frontend URL to the Gateway service 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-realm.json

Environment Configuration

Due to that Keycloak will be running behind a proxy it is important that Keycloak is configured to run behind a proxy. To set this up the following environment variable need to be set:

Gateway Service

In order to configure the Gateway Service, a blueriq-gateway-service.yml file needs to be present in spring.config.additional-location.  Here, you can specify the routes on which the Blueriq APIs are running and configure your OpenID Connect provider.

Route configuration

Routes are configured by setting a combination of properties: a route consists of an id, uri, predicates and filters. The id, uri an predicates properties are required when configuring a route.

spring:
  cloud:
    gateway:
      routes:
        - id: runtime
          uri: http://localhost:20000
          predicates:
            - Path=/runtime/**
        - id: dashboard
          uri: http://localhost:20001
          predicates:
            - Path=/dashboards/**

Runtime dashboard routing

The Gateway is a mandatory Service when using DCM in fail-over scenario, this is due to that a different Frontend solution is used to separate HTTP Sessions from each other. Each widget in a DCM dashboard gets its own HTTP Session. This is achieved by providing an additional filter to a Runtime or Runtime cluster route: The WidgetSession filter. This filter must contain the context path on which the route is registered. The value is limited to one context path, in case using multiple clusters several routes have to included in the configuration.

spring:
  cloud:
    gateway:
      routes:
		- id: cluster-1
          uri: http://localhost:20000
          predicates:
            - Path=/cluster-1/**
          filters:
            - WidgetSession=/cluster-1
        - id: cluster-2
          uri: http://localhost:20000
          predicates:
            - Path=/cluster-2/** 
          filters:
            - WidgetSession=/cluster-2
		- id: runtime
          uri: http://localhost:20001
          predicates:
            - Path=/runtime/**
          filters:
            - WidgetSession=/runtime

By default the WidgetSession filter assumes that the session cookies from the Runtime have the name JSESSIONID, when this is configured to another value a second parameter needs to be configured in the WidgetSession filter as the example below depicts.

spring:
  cloud:
    gateway:
      routes:
		- id: runtime
          uri: http://localhost:20001
          predicates:
            - Path=/runtime/**
          filters:
            - WidgetSession=/runtime, CUSTOM-SESSIONID

OpenID Connect Provider configuration

To use the BFF feature of the Gateway, at least one OpenID Connect Provider needs to be configured.

OpenID Connect Client configuration

The Gateway Service acts as an OpenID Connect client and therefore it needs to be configured as well. This however comes with some tricky configuration. All of the authentication requests pass through the gateway itself, including requests to gather configuration of the OpenID Connect resource server. This can result in startup failures when not configured properly.

spring:
  security:
    oauth2:
      client:
        provider:
          local-keycloak-provider:
            issuer-uri: http://keycloak.example.com:30007/realms/Blueriq
			user-name-attribute: preferred_username
        registration:
          keycloak:
            provider: local-keycloak-provider
            # Both scope openid and profile need to be active to retrieve the full information of the user.
			scope: openid, profile
            client-id: blueriq-gateway-client
            client-secret: SECRET
            authorization-grant-type: authorization_code
            redirect-uri: "{baseScheme}://{baseHost}{basePort}{basePath}/login/oauth2/code/keycloak"
			client-name: keycloak

The client provider needs to have the issuer-uri configured to exchange and validate tokens against. This should point to Keycloak itself.

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

The client-secret should contain the client secret that is generated in Keycloak for the client that is identified with the matching client-id.

The redirect-uri should point to a redirect location of the registered client, this is built up by a expandable base url and the login path. The base url is split into the scheme, host, port and path, so that we are able to support the Gateway Service running behind a Proxy server. The login path always consists of the following composition: /login/oauth2/code/<registrationId>. In our example, this would become /login/oauth2/keycloak.

External Session Configuration

To enable support for session offloading, the Gateway Service needs to be configured to connect to a Redis instance. This can be done via the following example:

spring:
	data:
  		redis:
    		host: redishost.exampe.com
			port: 6379 
 	session:
    	store-type: redis

When none of the above mentioned properties are explicitly set, the above settings are also the default. This means that Redis is the default session store type and it will try connecting to a locally running Redis instance on port 6379.

Login/Logout Redirect Configuration

When logging in or logging out of the Gateway you are either redirected to the source you came from or to a given redirect URI. To prevent a man in the middle attack, the Gateway enforces an allow list when redirecting. The allow list can be configured using the blueriq.gateway.security prefix when setting up the following properties. If either of these properties are not configured or contain empty values, the Gateway will fail to start.

**, http://localhost:20000/**, **/dashboard/default

**, http://localhost:20000/**, **/dashboard/default

Single Sign On logout configuration

Starting with version 1.0.4 the Blueriq Gateway Service has configurable SSO logout behavior. Use the blueriq.gateway prefix

false