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

1. Setup

To login using OpenID Connect an identity provider is needed.


Blueriq does not provide an identity provider. Blueriq uses Keycloak as identity provider in the integration tests.

For login via the UI, only the Authorization Code Flow (with response-type=code) is supported

Multiple OpenID Connect identity providers at the same time are not supported

Using the Material Angular theme together with OpenID Connect

The default Material theme based on Angular supports OpenID Connect authentication out-of-the-box, but it may require customizations depending on the desired usage. By default, the theme communicates the return URL (the URL that the user intended to open before being redirected to the login page) as part of the OpenID Connect redirect_url, which may cause problems if the return URL is dynamic and the identity provider has a whitelist of allowed redirect_url values. The default theme can be changed as desired to support this use-case, if needed.

2. How does it work



3. Exception handling

If any exception occurs, a page with a custom exception is shown.

Detailed information about the exception can be found in the log when your log level is on DEBUG

4. How to configure an OpenID Connect identity provider 

The identity provider needs to be configured in application.properties and added to blueriq.security.auth-providers-chain.  The client id, client secret and public key are mandatory and can be extracted from the identity provider.

Blueriq uses the id token to extract the information needed to login. Username, teams and roles from id token are mapped to Blueriq UserData. For the roles and teams the path to the roles and teams in the token can be configured. 

There are some optional validation checks that can be executed when validating the access token. One of them is the audience check. This check can be configured.


application.properties
# Connection
# Defined the login type used in Blueriq. Possible values: form-login, openid-connect. 
# This property is not mandatory and the default value is form-login. 
# If openid-connect is chosen, the properties below this one need to be set as well.
blueriq.security.login-type=openid-connect
# Configure your custom autentication provider. 'myProvider' need to be set in blueriq.security.auth-providers-chain.
blueriq.security.auth-providers.myProvider.type=openid-connect
blueriq.security.openid-connect.client-secret=clientSecret
blueriq.security.openid-connect.public-keys.<key id>=<base64 public key>
blueriq.security.openid-connect.client-id=clientId
 
# Identity provider endpoints
# Used to get the id token from the identity provider.
blueriq.security.openid-connect.token-endpoint=http://[host]:[port]/auth/realms/master/protocol/openid-connect/token
# Used to authorize a user in the identity provider.
blueriq.security.openid-connect.authorization-endpoint=http://[host]:[port]/auth/realms/master/protocol/openid-connect/auth
 
# Paths
# Define the path to roles and teams in the id token. 
# The full path needs to be defined, each depth node must be separated by a comma.
blueriq.security.openid-connect.roles-path=realm_access,roles
blueriq.security.openid-connect.teams-path=teams


# Role and Team Mappings
# Map one OpenID Connect role to zero, one or more Blueriq roles
# OpenID Connect roles that are not mapped remain unchanged
blueriq.security.openid-connect.role-mapping.role1=blueriqRole1,blueriqRole2
blueriq.security.openid-connect.team-mapping.team1=blueriqTeam1,blueriqTeam2
 
# Validations
# If this property is set to true, an extra check on the id token is made: 
# 'Validate that the aud (audience) Claim contains its client_id value registered at the Issuer identified by 
# the iss (issuer) Claim as an audience.'
blueriq.security.openid-connect.check-audience=true

5. REST API

Blueriq Runtime exposes two endpoints to authenticate with OpenId Connect. These endpoints can be used as described in the algorithm at section 5.3.

5.1. Login Endpoint

GET /api/v2/oidc/login

Description

Login endpoint that returns the URL required for calling the authorization endpoint of OpenID Connect Identity Provider.

Parameters
Query ParameterExpected TypeDescriptionRequired
redirect_uristringRedirection URI to which the response will be sent.true

5.2. Callback Endpoint

POST /api/v2/oidc/callback

Description

Exchanges authorization code for token and authenticates user in Blueriq.

Parameters
Query ParameterExpected TypeDescriptionRequired
codestringThe authorization code to be exchanged for tokens.true
redirect_uristringThe Redirection URI that was used to obtain the authorization code.true
statestringOpaque value used to maintain state between the request and the callbacktrue

5.3. Algorithm

The algorithm that can be used in order to login is the the following:

(1) The front-end makes an XHR request to the API start endpoint.

(2) Back-end responds with 401.

(3) Front-end changes window.location to Login Endpoint and sends the suitable parameters (the redirect_uri)

(4) Login Endpoint returns the URL needed to access the authorization endpoint of the OpenId Connect Identity Provider using the parameters sent at step (3) and client-id from application.properties.

(5) User logs in using Identity Provider.

(6) Identity Provider redirects to the front-end application (this should be a special page with Javascript code that knows how to read the authorization code from the URL and how to call Callback Endpoint) sending the authorization code and the state.

(7) The front-end makes an XHR request to the Callback Endpoint sending the authorization code, redirect_uri and state.

(8) Callback Endpoint

  • exchanges the authorization code to authorization and identity tokens,
  • sets the current user in the Spring security context and
  • responds with 200.

(9) The front-end changes windows.location to the URL from (1)

Didn't find the answer you were looking for? Try the advanced search!