Feijuca.Auth – Part 2: Configuring, Creating Realm, and using Feijuca.Auth.API

This is the second article in a series about using Feijuca.Auth.

If you landed directly on this post, I recommend reading the first part:

Part 1: Understanding and Configuring Feijuca.Auth

Introduction
In the first article, we introduced the Feijuca.Auth project—its purpose, concepts, Now we'll move forward to the configuration basics.

Prerequisites
Before we dive in, make sure you have the following running:

✅ Keycloak
You’ll need a Keycloak instance running—either locally or on a server. The official Docker image can be pulled from:
👉 https://www.keycloak.org/getting-started/getting-started-docker

✅ MongoDB
Feijuca.Auth uses MongoDB to store metadata about your Keycloak server—like its URL, client secret, and realm configuration.

⚠️ Note: Feijuca.Auth does not store any user data. You own the instance entirely—Feijuca.Auth only needs your connection string.

💡You can use mongodb atlas to create a free mongodb instance.

💡 You also can contribute and add support to the db from your choice.

Initial Setup
Once both Keycloak and MongoDB are running, follow this required configuration step before launching Feijuca.Auth:

🔗 Keycloak Mandatory Configuration Guide

This step teaches you how to configure a client in the master realm (the default Keycloak realm). This client will have permissions required to manage other realms via Feijuca.Auth.

For further technical details, you can always refer to the full documentation:

📘 Feijuca.Auth Docs – Getting Started

Running Feijuca.Auth
Once everything is configured, you can run Feijuca.Auth using Docker:

docker run \
-e ConnectionString="mongodb://<username>:<password>@<host>:<port>" \
-e DatabaseName="FeijucaAuth" \
coderaw/feijuca-auth-api:latest

💡 You can change the database name and connection string as needed.

What is Feijuca.Auth.API?
Feijuca.Auth.API exposes a RESTful API that simplifies Keycloak realm management. With this module, you can:

Create users, groups, roles
Manage clients and client scopes
Create and configure new realms

Initial Realm Setup Endpoint
Before doing anything else, you need to call the initial configuration endpoint. This step sets up the realm, client, user, and default settings needed by Feijuca.Auth to operate.

Here’s the required curl request:

curl https://localhost:7018/api/v1/configs/new-realm \
--request POST \
--header 'Content-Type: application/json' \
--data '{
"realmAdminUser": {
"email": "", // Set admin user email
"password": "" // Set admin user password
},
"client": {
"clientId": "feijuca-auth-api" // Must match the client name configured in the master realm
},
"clientSecret": {
"clientSecret": "secret-retrieved-from-client" // Paste the actual client secret here
},
"serverSettings": {
"url": "" // The URL of your running Keycloak instance, e.g., https://localhost:8080
},
"realm": {
"name": "", // Name of the new realm, or an existing one
"issuer": "serverSettings-url/realmname"
}
}'

This will return a success status code and a message confirming that the initial configuration is complete.

🔁 After executing this endpoint, you must restart the Feijuca.Auth container. On startup, it will load the configuration from MongoDB and initialize correctly.

What Does This Endpoint Do?
This endpoint handles the essential setup required for both the Feijuca.Auth.Api and the Feijuca.Auth NuGet package to function properly. One of its core responsibilities is enabling multitenancy support.

Feijuca automatically maps the tenant user attribute into the token payload, which is crucial for implementing tenant-based access control. Every new user created via Feijuca will have a default tenant assigned, which corresponds to the name of the realm in which the user is being created.

Behind the scenes, this endpoint performs several operations—such as creating clients, roles, default configurations, and mappings—so you don't have to worry about the heavy lifting. It streamlines the setup process, allowing you to start building with Feijuca.Auth right away.

What’s Next?
Once your realm is configured and the container is restarted, you’ll be able to use the REST endpoints provided by Feijuca.Auth to perform all sorts of operations in your realm(s).

In the next post, I’ll walk through how to protect your own API endpoints using Feijuca.Auth.

Stay Tuned
If you’re building multitenant applications or need a simplified way to manage realms via Keycloak, Feijuca.Auth is designed to help you do just that with minimal setup and full control.

➡️ Explore the documentation
➡️ Follow me on Dev.to to get updates on the next part!