Keycloak Bulk User Import via RestAPI

A simple Python proof of concept for importing large numbers of users into Keycloak efficiently using the Partial Import API.

Warning

I tried incremental 100 - 5.000 Users. With a fresh DB it worked without issues.
Performance was good, with 5,000 users being imported in under a few seconds on my local development system inside docker.
However, performance may vary depending on your system specifications and Keycloak server configuration.

☝️ Sometimes the API Call even fails (500) with an SQL-Error, but keep in mind that this is without a DB in standalone 🏁

Overview

This tool allows you to bulk import users into Keycloak with configurable options for handling existing resources. It uses Keycloak's Partial Import API to efficiently process large sets of user data.

Features

• Import hundreds or thousands of users in a single operation
• Configure conflict resolution strategy (OVERWRITE, SKIP, or FAIL)
• Optional group assignment during import
• Performance metrics for import operations

Note

Can it be structured better, sure. Can there be less hard-coded values in main.py? YES . This is a proof of concept and can be significantly improved with proper configuration management, error handling, and modular design.

TODOs

• Split the if __name__ == "__main__": ... into two functions
• Implement proper error handling and logging
• Add configuration management (e.g., using environment variables or a config file)
• Implement unit tests for core functions

Code Structure

The codebase is organized as follows:

• main.py - Contains all the functionality:
  • get_admin_token() - Authenticates with Keycloak and retrieves an admin token
  • partial_import_users(users_data) - Performs the partial import operation
  • Main execution block with example import operations
    • as well as the possibility to overwrite them to be assigned to groups

Requirements

• docker
• python-knowhow

Installation

1. Clone the repository:

git clone https://github.com/yourusername/keycloak-bulk-import.git cd keycloak-bulk-import

Configuration

Edit main.py to configure your Keycloak connection (if needed, works yet):

# Keycloak config
KEYCLOAK_URL = "http://keycloak:8080"  # Update with your Keycloak URL
REALM = "my-realm"                     # Update with your target realm
ADMIN_USER = "admin"                   # Update with admin username
ADMIN_PASSWORD = "password"            # Update with admin password

Usage

docker compose up

Which imports 999 Users and assigns them to groups by overwritting in a second run/API call.

Debugging

This project supports VSCode debugging.

To debug:

Enable the alternative entrypoint: (in the compose.yaml)

Set breakpoints in the code Use the VSCode "Run and Debug" feature (F5) For manual debugging, you can add print statements or modify the logging verbosity.

Run: docker compose up

Verifying Results in Keycloak Admin Console

To verify that the import worked correctly:

• Login to your Keycloak Admin Console (admin/password) at http://localhost:8800/admin/

• Navigate to your configured realm (e.g., "my-realm")

• Click on "Users" in the left menu

• Use the search box to find imported users (e.g., search for "user_" to find test users)

• Verify user details, groups, and other attributes

Testing Group Assignments

If you imported users with group assignments:

• In the Keycloak Admin Console, navigate to "Groups"

• Select a group that was assigned to users

• Click on the "Members" tab

• Verify that the expected users appear in the group membership list

Troubleshooting

• 401 Unauthorized errors: Check your admin cedentials and make sure the user has appropriate permissions
• 400 Bad Request errors: Validate your JSON payload structure against the Keycloak API requirements
• Connection errors: Verify that your Keycloak URL is correct and the instance is running

References

Keycloak Server Administration Guide

Warning

The API definition does not match the real API behavior. The file parameter in the API documentation is not actually supported. Instead, the import data should be sent in the request body as JSON.

Keycloak Partial Import Documentation