You are viewing the documentation for Blueriq 13. 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




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 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 provivider 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. Angular Front-End

Blueriq exposes two endpoints for customers that are using Angular Front-End. 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) Angular Front-End makes AJAX call to 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 Identity Provider.

(6) Identity Provider redirects to the Angular Front-End (this should be a special page with javascript code that knows how to read the authorization codefrom URL and how to call Callback Endpoint) sending the authorization code and the state.

(7) Angular Front-End makes an AJAX call to 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) Angular changes windows.location to the URL from (1)

  • No labels

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