SSO Integration: Configure Keycloak with the MB connect line Portal

This article describes the steps required to configure Single Sign-On (OpenID Connect) between any Keycloak instance and the MB connect line Gatekeeper portal.

Applies to: • RSP • RSP.virtual

Prerequisites

Keycloak instance (version 20+) with HTTPS
Access to the Keycloak Admin Console
Access to the portal backend as an administrator
SSO licensing enabled in the portal
Network access from the portal server to the Keycloak instance (server-to-server, port 443)
- DNS resolution must work on the portal server
- Firewalls must allow the connection

Prepare Keycloak

Step 1: Determine Realm-URL

The base URL of a Keycloak realm has the following format:

https://<keycloak-host>/realms/<realm-name>

In the following, <REALM_URL> is used as a placeholder for this base URL.

Step 2: Verify OIDC discovery

Each Keycloak realm provides a discovery endpoint automatically:

<REALM_URL>/.well-known/openid-configuration

This returns all endpoint URLs. Check accessibility:

curl -s <REALM_URL>/.well-known/openid-configuration | jq .

From the response you need:

Discovery field	Portal setting
issuer	Domain (ISS)
authorization_endpoint	Authorization endpoint
token_endpoint	Secure token endpoint / Refresh token endpoint
jwks_uri	JWKS metadata endpoint

Step 3: Create client

In the Keycloak Admin Console under Clients > Create client:

Setting	Value	Description
Client type	OpenID Connect
Client ID	freely selectable (e.g. portal-sso)	Entered in the portal as "Client ID"
Client authentication	On	Confidential client — generates a client secret
Authorization	Off	UMA/fine-grained auth not required
Standard flow	On	Authorization Code Flow (required)
Direct access grants	Optional	Only useful for testing (password grant)
Service account roles	Optional	Only if client credentials grant is required
Implicit flow	Off	Deprecated, not required

After saving, you will find the Client Secret under the Credentials tab.

Step 4: Configure redirect URI

Under the Settings tab of the client:

Setting	Value
Valid redirect URIs	<https://<portal-host>>/portal/index.php?option=com_sso
Web origins	<https://<portal-host>>

Note:

For testing purposes, * can be used as a redirect URI. In production, the URI should always be restricted.

Step 5: Verify signature algorithm

Under Clients > <your client> > Advanced > Fine Grain OpenID Connect Configuration:

Setting	Recommended value
ID Token Signature Algorithm	RS256 (default)
Access Token Signature Algorithm	RS256 (default)

Warning:

Please use RS256, not HS256. The portal verifies tokens via the JWKS endpoint (public key). With HS256, verification fails with "unable to lookup correct key" because JWKS only contains public keys.

Step 6: Create user

Under Users > Add user, create a user. Required fields:

Username (is issued as preferred_username in the JWT)
Email (is issued as email in the JWT)
First name + Last name (are issued as name, given_name, family_name)
Email verified: On

Set a password under the Credentials tab.

Note:

Ensure that the user has the default realm roles (usually assigned automatically) so that the Keycloak Account Console works properly.

Configure portal

In the portal backend

Step 1: Navigate to section: Access

Field	Value	Source
Active	Yes	—
Client ID	<your client ID>	Keycloak: Client ID (Step 3)
Client Secret	<your secret>	Keycloak: Clients > Credentials
Domain (ISS)	<REALM_URL>	Discovery: issuer
JWKS Metadata endpoint	<REALM_URL>/protocol/openid-connect/certs	Discovery: jwks_uri
Authorization endpoint	<REALM_URL>/protocol/openid-connect/auth	Discovery: authorization_endpoint
Secure token endpoint	<REALM_URL>/protocol/openid-connect/token	Discovery: token_endpoint
Refresh token endpoint	<REALM_URL>/protocol/openid-connect/token	Same URL as token endpoint
Scope	openid profile email	Space-separated

Warning:

Enter all URLs completely and do not shorten them.
Enter the scope space-separated and do not use commas.

Step 2: Navigate to section: Security

Field	Value
Auth type	Code
Grant type	Authorization Code
Algorithm	RS256

Step 3: Navigate to section: Default user data

These fields define which JWT claim the portal uses to read the username and email address. The value must match a valid claim name from the id_token.

Field	Recommended value	Alternatives	Description
User info: field for name	name	given_name, preferred_username, family_name	Defines the display name in the portal
User info: field for email	email		Primary identifier for user mapping

Warning:

The configured field name must exactly match the claim name in the JWT.
Keycloak uses standard OIDC claim names (e.g. name, given_name),
not firstName, lastName or similar.
Incorrect mapping will cause the integration to fail.

Verification

Step 1: Quick test with curl

Check whether the Keycloak server is reachable from the portal server:

# Execute on the PORTAL SERVER:

curl -v https://<keycloak-host>/realms/<realm>/.well-known/openid-configuration

Expected result: HTTP 200 with JSON response. If errors occur, check:

DNS resolution (nslookup <keycloak-host>)
TLS certificate (must be trusted by the portal server)
Firewall (port 443 open)

Step 2: Test token request

curl -s -X POST "<REALM_URL>/protocol/openid-connect/token" \
--data-urlencode "grant_type=password" \
--data-urlencode "client_id=<client-id>" \
--data-urlencode "client_secret=<client-secret>" \
--data-urlencode "username=<username>" \
--data-urlencode "password=<password>" \
--data-urlencode "scope=openid profile email" | jq .

Expected response:

{
"access_token": "eyJ...",
"id_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 300,
"scope": "openid profile email"
}

Note:

If id_token is missing, openid is not included in the scope.

Step 3: Validate id_token

Decode the payload of a JWT (without signature verification):

echo "<id_token>" | cut -d. -f2 | base64 -d 2>/dev/null | jq .

Expected claims:

{
"iss": "<REALM_URL>",
"aud": "<client-id>",
"name": "Max Mustermann",
"email": "max@example.com",
"email_verified": true,
"given_name": "Max",
"family_name": "Mustermann",
"preferred_username": "maxm"
}

SSO Integration: Configure Keycloak with the MB connect line Portal