Keycloak Integration Guide (v26.2.0)

📋 Overview

This guide demonstrates how to integrate Keycloak with GraphXR using multiple authentication methods:

• OpenID Connect (OAuth2) - Standard OAuth2 authentication flow
• SAML - Enterprise SAML integration
• iframe Authentication - Embedded authentication for iframe scenarios

📑 Table of Contents

• Prerequisites
• 1. User Management
• 2. OpenID Connect Integration
• 3. SAML Integration
• 4. iframe Authentication
• 5. Testing the UserInfo API

Prerequisites

Requirements

• Docker installed and running
• Keycloak v26.2.0
• GraphXR server instance
• Node.js and Yarn (for iframe demo)

Quick Start

1. Start Keycloak:

   bash ./run.sh

2. Access Keycloak Admin Console:

   • URL: http://localhost:8080
   • Default credentials: admin / admin

3. Import Pre-configured Clients (Optional):

   • Import GraphXR-iframe-demo.json in Keycloak under "Clients" section
   • Import GraphXR-OpenID.json in Keycloak under "Clients" section

Note: The run.sh script will start Keycloak in a Docker container with H2 database persistence.

1. User Management

Creating Test Users

1. Navigate to the Keycloak Users page:

   • URL: http://localhost:8080/admin/master/console/#/master/users

2. Click "Create new user" and add the following test users:

   Email	Password	First Name	Last Name
   demo@demo.com	demo@demo.com	Demo	User
   example@example.com	example@example.com	Example	User

3. Important Configuration Steps:

   • Set "Email verified" to ON
   • Under the "Credentials" tab, set the password
   • Disable "Temporary" to avoid forcing password change on first login

Tip: You can create additional users as needed for testing different scenarios.

2. OpenID Connect Integration

2.1 Create OpenID Connect Client

1. Navigate to Client Creation:

   • URL: http://localhost:8080/admin/master/console/#/master/clients/add-client

2. Configure Basic Settings:

   Client Type: OpenID Connect
   Client ID: GraphXR-OpenID
   Name: GraphXR OpenID
   Description: OpenID Demo
   

   Click "Next"

3. Configure Capability Settings:

   Enable the following options:

   • ✅ Client authentication
   • ✅ Authorization
   • ✅ Standard flow
   • ✅ Direct access grants

   

   Click "Next"

4. Configure Access Settings:

   Root URL: https://localhost:9000
   Home URL: https://localhost:9000/oauth2/login
   Valid redirect URLs: https://localhost:9000/oauth2/login/callback
   Valid post logout redirect URIs: https://localhost:9000/oauth2/logout
   Web origins: https://localhost:9000
   

   Click "Save"

2.2 Configure GraphXR for OpenID Connect

1. Retrieve OpenID Configuration:

   • Access: http://localhost:8080/realms/master/.well-known/openid-configuration
   • This provides all necessary endpoints

2. Get Client Secret:

   • Navigate to your client in Keycloak
   • Go to the "Credentials" tab
   • Copy the Client Secret value

   

3. Update GraphXR Configuration:

   Add the following to your GraphXR config.js file:

   oauth2: {
     loginShowName: "Keycloak",
     authorizationURL: 'http://localhost:8080/realms/master/protocol/openid-connect/auth',
     tokenURL: 'http://localhost:8080/realms/master/protocol/openid-connect/token',
     userProfileURL: "http://localhost:8080/realms/master/protocol/openid-connect/userinfo",
     clientID: "GraphXR-OpenID",
     clientSecret: "{YOUR_CLIENT_SECRET}", // Replace with actual client secret
     scope: 'openid,email,profile',
     callbackURL: "https://localhost:9000/oauth2/login/callback",
     profileMapping: {
       firstName: "family_name",
       lastName: "given_name",
       email: "email",
     },
   },

4. Replace Placeholder:

   • Replace {YOUR_CLIENT_SECRET} with the actual client secret from step 2

Security Note: Keep your client secret secure and never commit it to public repositories.

3. SAML Integration

3.1 Create SAML Client

1. Navigate to Client Creation:

   • URL: http://localhost:8080/admin/master/console/#/master/clients/add-client

2. Configure Basic Settings:

   Client Type: SAML
   Client ID: GraphXR-SAML
   Name: GraphXR SAML Demo
   Description: A GraphXR SAML Demo
   

   Click "Next"

3. Configure Access Settings:

   Root URL: https://localhost:9000
   Home URL: https://localhost:9000/saml/login
   Valid redirect URLs: https://localhost:9000/*
   Valid post logout redirect URIs: https://localhost:9000/saml/logout
   IDP-Initiated SSO URL name: GraphXR-SAML
   Master SAML Processing URL: https://localhost:9000/saml/login/callback
   Name ID format: email
   

   Click "Save"

4. Add SAML Attribute Mappers:

   Navigate to: Client scopes > GraphXR-SAML-dedicated > Add mapper > By configuration

   Add the following mappers:

   Mapper Type	Name	User Attribute	SAML Attribute Name
   User Property	email	email	email
   User Property	firstName	firstName	firstName
   User Property	lastName	lastName	lastName

   For each mapper:

   • Select "User Property" as mapper type
   • Set SAML Attribute Name Format to "Basic"
   • Click "Save"

3.2 Configure GraphXR for SAML

1. Retrieve SAML Metadata:

   • Access: http://localhost:8080/realms/master/protocol/saml/descriptor
   • This XML contains the IdP configuration

2. Extract X.509 Certificate:

   • Locate the <ds:X509Certificate> element in the XML
   • Copy the certificate value (between the opening and closing tags)

3. Update GraphXR Configuration:

   Add the following to your GraphXR config.js file:

   saml: {
     loginShowName: "Keycloak-saml",
     path: "https://localhost:9000/saml/login",
     entryPoint: "http://localhost:8080/realms/master/protocol/saml/clients/GraphXR-SAML",
     cert: '{YOUR_CERT}', // Replace with the X509 certificate
     profileMapping: {
       email: "nameID",
       firstName: "firstName",
       lastName: "lastName"
     }
   },

4. Replace Placeholder:

   • Replace {YOUR_CERT} with the actual X.509 certificate value

4. iframe Authentication

4.1 Understanding the iframe OAuth Flow

The iframe authentication allows embedding GraphXR in a third-party application with seamless authentication:

sequenceDiagram
    participant TW as Third-Party Web
    participant TS as Third-Party Server
    participant GW as GraphXR Web
    participant GS as GraphXR Server

    TW->>TS: 1. Login request (OAuth2/SAML)
    TS-->>TW: 2. Login response + userInfo (set token/uid in session)
    TW->>GW: 3. PostMessage(token/uid) or embed URL with token/uid
    GW->>GS: 4. AutoLogin request (with token/uid)
    GS->>TS: 4.1 Validate token & request userInfo
    TS-->>GS: 4.2 Return userInfo
    GS-->>GW: 5. AutoLogin success (set session/token)
    GW-->>TW: 6. Display GraphXR without login screen

Loading

4.2 Configure iframe Authentication in GraphXR

Add the following to your GraphXR config.js file:

iframeAuth: {
  keyName: "token",
  userProfileURL: "http://localhost:8080/realms/master/protocol/openid-connect/userinfo",
  profileMapping: {
    email: "email",
    firstName: "family_name",
    lastName: "given_name",
  }
},

4.3 Configure CORS in GraphXR

Update your GraphXR server config.js to allow iframe embedding:

cors: {
  shareDefault: true,            // Allow /share/default/ProjectName
  allowAnonymousQuery: true,     // Allow /api/neo4j/executeCommand to run Cypher
  adminSub: true,                // Allow /admin/sub/users to be embedded in iframe
  origin: "*",                   // Allow all origins (or specify allowed domains)
  referrerPolicy: { policy: "unsafe-url" },
  frameguard: false,             // Allow all GraphXR pages to be embedded in iframe
  contentSecurityPolicy: false,
},

Security Warning: The configuration above is permissive for development. In production:

• Restrict origin to specific domains instead of "*"
• Review security implications of allowAnonymousQuery
• Consider stricter CORS policies based on your requirements

4.4 Run the Demo Application

1. Install Dependencies and Start Server:

   yarn && yarn start

2. Access the Demo:

   • URL: http://localhost:3080
   • The demo app is located in index.js

3. Embedding GraphXR with Token:

   You can embed GraphXR using a URL with token parameters:

   https://GraphXRServer:9000/p/default/demo-project?token={YOUR_TOKEN}&email={YOUR_EMAIL}
   

   Supported paths:

   • /p/default/* - Specific projects
   • /projects - Projects list
   • /settings - Settings page

4. Example iframe Implementation:

   const iframe = document.createElement('iframe');
   iframe.src = `http://localhost:9000/projects?token=${encodeURIComponent(accessToken)}&email=${encodeURIComponent(email)}`;
   iframe.width = "100%";
   iframe.height = "800";
   iframe.style = "border: 1px solid #ddd; border-radius: 4px; box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);";
   iframe.title = "GraphXR Projects";
   iframe.loading = "lazy";
   document.body.appendChild(iframe);

Note: See ./index.js for the complete implementation reference.

5. Testing the UserInfo API

5.1 Verify API Response

Before implementing iframe authentication, ensure your UserInfo API returns the correct email format:

Required Response Format:

{
  "email": "user@example.com",
  "family_name": "Doe",
  "given_name": "John",
  ...
}

5.2 Test Script

Use the following script to test the Keycloak UserInfo API:

const token = "YOUR_ACCESS_TOKEN";      // Replace with actual token
const email = "YOUR_EMAIL";             // Replace with actual email
const userInfoApi = "http://localhost:8080/realms/master/protocol/openid-connect/userinfo";

fetch(userInfoApi, {
  method: "GET",
  headers: {
    "Accept": "application/json, text/plain, */*",
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
    "Email": `${email}`,
  },
})
  .then((res) => res.json())
  .then((data) => {
    console.log("UserInfo Response:", data);
    
    // Verify required fields
    if (data.email) {
      console.log("✓ Email field present:", data.email);
    } else {
      console.error("✗ Email field missing!");
    }
  })
  .catch((error) => {
    console.error("API Error:", error);
  });

5.3 Getting an Access Token

To obtain a test access token:

1. Using Direct Access Grants:

   curl -X POST "http://localhost:8080/realms/master/protocol/openid-connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=GraphXR-OpenID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "username=demo@demo.com" \
     -d "password=demo@demo.com" \
     -d "grant_type=password"

2. Response will contain:

   {
     "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
     "expires_in": 300,
     "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",
     ...
   }

3. Use the access_token value in your test script above.

5.4 Troubleshooting

Issue	Solution
401 Unauthorized	Check if token is valid and not expired
Missing email in response	Verify user has email set and "email" scope is included
CORS errors	Ensure CORS is properly configured in GraphXR
Token expired	Request a new token using the refresh token or re-authenticate

---

📚 Additional Resources

• Keycloak Documentation
• OpenID Connect Specification
• SAML 2.0 Documentation
• GraphXR Configuration Guide (refer to GraphXR documentation)

🔒 Security Best Practices

1. Never expose sensitive credentials in public repositories
2. Use HTTPS in production environments
3. Restrict CORS origins to specific domains
4. Implement token expiration and refresh mechanisms
5. Regularly update Keycloak and dependencies
6. Use different client secrets for development and production
7. Enable multi-factor authentication for admin accounts

📝 License

This demo configuration is provided as-is for testing and development purposes.

---

Last Updated: May 21, 2026
Keycloak Version: 26.2.0