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 JAR file needs to be deployed to a supported application server, see Installing Runtime. The application requires a config location to specify the configuration outlined below. Note that the DCM 2.0 beta 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 uses a Redis cache to offload session state. This is to guarantee that the Gateway Service keeps working in a multi-node setup. This option is optional. 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.

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.

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.

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 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 paths on which the route is registered. The value can be a comma separated list when the route contains multiple path predicates.

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

OpenID Connect Provider configuration

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

Route configuration

Routes to an OpenID Connect Provider needs to be configured with two additional filters, the RewriteLocationResponseHeader and BackendForFrontend filter.

spring:
  cloud:
    gateway:
      routes:
        - id: keycloak
          uri: http://localhost:8080
          predicates:
            - Path=/realms/**, /resources/**
          filters:
            - RewriteLocationResponseHeader=AS_IN_REQUEST, Location, ,
            - BackendForFrontend

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.

blueriq:
  gateway:
    oauth2:
      registration-extensions:
        keycloak:
          end-session-endpoint: http://localhost:20010/realms/Blueriq/protocol/openid-connect/logout
spring:
  security:
    oauth2:
      client:
        provider:
          local-keycloak-provider:
            client-name: Keycloak-Login
            # When the issuer-uri is not set the authorization-uri, token-uri need to be set.
            # We cannot set the issuer-uri due to that the gateway is not able to resolve the correct issuer from within our gateway.
            token-uri: http://localhost:20010/realms/Blueriq/protocol/openid-connect/token
            authorization-uri: http://localhost:20010/realms/Blueriq/protocol/openid-connect/auth
			jwk-set-uri: http://localhost:8080/realms/Blueriq/protocol/openid-connect/certs
			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: 0Hv2WMsjIsBdHsAq3bNycIEKgCWaluEf
            authorization-grant-type: authorization_code
            redirect-uri: "{baseScheme}://{baseHost}{basePort}{basePath}/login/oauth2/code/keycloak"

The client provider needs to have the token-uri, authorization-uri, jwk-set-uri properties configured to exchange and validate tokens against. These URIs should point to the host and port where the Gateway is running on; not 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 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.

Since we are not able to use the issuer-uri we need to provide some extensions to our oath2 registration. In order for the Gateway Service to logout and login properly we need to provide the end-session-endpoint in the blueriq.gateway.oauth2.registration-extensions. Each registered spring.security.oauth2.client.registration is expected to also have blueriq.gateway.oauth2.registration-extensions properties mapped. In the registration-extensions the end-session-endpoint need to be provided for the corresponding client.registration.

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:
  redis:
    host: localhost
	port: 6379 
  session:
    store-type: redis

By default the Gateway Service stores its session in memory.