You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.

Introduction

The Gateway Service acts as gateway between your front facing applications and your APIs. Instead of directly letting the front facing applications talk to the Blueriq APIs it will first pass through the Gateway Service. The Gateway Service routes the traffic which comes into the service to the appropriate API, by doing so this service is able to enhance requests and response messages from and to the APIs.

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

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.



Auth flow

The diagram above is a simplified version of the actual login flow to illustrate how OAuth is integrated when using the Gateway Service. The "verify token in session" checks whether the current HTTP Session contains a token or not, if it does then it will be added to the API request (for example to the Blueriq UI Rest API).

The authenticate flow from the gateway to Keycloak is in reality the OAuth Authorization Code Flow, where the intermediate requests for token exchanges are intercepted by the Gateway so that no token information is leaked to outside of the gateway. Once the token is acquired the gateway will send a Secure Session Cookie back to frontend. 

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:

Environment variableValue
KC_PROXYpassthrough
KC_HOSTNAME_STRICTfalse
PROXY_ADDRESS_FORWARDINGtrue

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.

PropertyDescriptionExample
idIdentification of the routeRuntime
uriURI to which the gateway proxies the requesthttp://localhost:20000
predicates

Predicates which are tested against the request
and only passed if all predicates are positive

Path=/runtime/**

Matches all requests which start with /runtime

filters

Filters which can be applied to the request or response

PrefixPath=/dcm-dashboard

Adds a /dcm-dashboard path prefix to the downstream requests. This should be the context path where the target is running on.

Route configuration
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.

Route 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.

Session cookie configuration
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.

OpenID Connect/OAuth2 configuration
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.

building the redirect-uri

Because the Gateway Service might run behind a Proxy server, it uses the X-Forwarded and Host headers when building redirect-uri. If the uri is configured to be expandable by using for example ${baseHost} in the uri, then the X-Forwarded-Host or Host header will be used as its value.

Running behind a virtual context root

It is possible that you are running the Gateway behind a virtual context path in your proxy.

Typically this context path is removed when moving to your infrastructure behind the proxy. The Gateway Service needs to be able to build URLs which are redirect URLs that go back to the Gateway Service itself. In case you are running behind such context path, you will need to adjust and assign two properties to include that context path. 

These properties use template variables and expansion, meaning that you can either provide a full URL such as  http://example.com:8080/context or use template variables which be expanded using the request that started call. 

blueriq.gateway.post-logout-redirect-base-uri - needs to be configured, by default the redirect base uri is configured to {baseScheme}://{baseHost}{basePort}{basePath}, in case of a context path you will need to set append context path. 

spring.security.oauth2.client.registration.keycloak.redirect-uri - needs to be altered to include the context path, between the {basePath} and /login/oauth2/code/keycloak url.

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:

External session configuration
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.

PropertyDescriptionExample
login-redirect-allow-listList of allowed login redirect URIs. These URIs can be configured using ant path matching.
**, http://localhost:20000/**, **/dashboard/default
logout-redirect-allow-listList of allowed logout redirect URIs.  These URIs can be configured using ant path matching
**, 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

PropertyDescriptionExample
sso-logout

Boolean indicating whether when logging out the Single Sign On session should be ended as well.


Default: true

false