Mifos X - Technical manual for configuring OIDC (Zitadel) using Docker on Windows

Provide clear and concise instructions for implementing ZITADEL as a plug-in in Apache Fineract and the Mifos Webapp on the Windows 11 Home x86_64 operating system. The configuration steps described are the same for instances running either PostgreSQL or MariaDB. These instructions are designed to be executed by users with basic technical skills.

Target Audience

Username	Descripción
General Public	Users must have basic technical knowledge. It is recommended to have a basic understanding of web service integration and credential management, as well as plug-in integration in Apache Fineract.

System requirements

Hardware:

8Gb RAM
2 vCPUs (Intel x86 64bits or AMD x86 64bits)
32Gb Storage

Software:

Windows 11 Home x86_64 bits Operating System
Docker 25.03
Powershell
Apache Fineract 1.21.1

Instructions:

The commands shown below must be reviewed in a text editor and adapted to your specific configuration. Running them without verification may cause installation failures.

ZITADEL Console Setup
Open a web browser and go to https://zitadel.com Click on “Sign up”.
Log in or create an account.
ZITADEL allows you to sign in using a Google account or with email and password.
Accept the required permissions for the Google connection with ZITADEL.

Enter a username, accept the terms of service, and proceed to create the first instance.
Set up your environment by creating an instance using the “Create your first instance” option.
Assign a name to the instance and a name for your new organization.
Select a region. This cannot be changed after creating the instance.
Create a user. The user created in this step will be the Zitadel console administrator.
Confirm that the configuration is assigned correctly.
Use the user created in the previous step to sign in to the newly created instance. Go to “Instances” section Select the newly created instance
Enter the sign-in credentials.
The first time you sign in, you will be asked to set up two-factor authentication. This setup is optional. To take full advantage of ZITADEL features, it is recommended to configure two-factor authentication using the Google Authenticator app.
Once inside the console, we can start creating projects.

ZITADEL Cloud Configuration for Backend API

Go to the “Projects” tab to create a new project.

Click on the “Create New Project” button.

Assign a name to the project.

Now, create a new application.

In the Applications section, click the “New” button.

This will be the backend of our project. Assign a name. For the application type, select “API”. Press the “Continue” button.
For the authentication method, set it to “BASIC”.
Review the configuration. If correct, click the “Create” button.
Once created, you can save the data generated by ZITADEL for API usage. This data can be generated again later. It will be used and generated again in the following steps of this manual.
The data obtained in the previous step will be identified as: Backend ‘client ID’ and ‘client secret’.

ZITADEL Cloud Configuration for Mifos WebApp
Return to the main section of your project. Create a new application.
This will be the connector to the Mifos Web App for our project (frontend). Assign a name. For the application type, select “Native”. Press the “Continue” button.
For the authentication method, set it to “PKCE”.
To perform this step, you need to know the URL of the WebApp for your Mifos X Platform instance. For example, if it is on a local environment: http://localhost:4200 If you have a DNS: https://sandbox.mifos.community Add the extension /#/login after the URL: http://localhost:4200/#/login
Once the data is confirmed, click the “Create” button.
ZITADEL will display the client ID for our application (this is different from the one generated for the API). It can be referenced later. It will be used in the following steps of this manual.
ZITADEL will display the configuration of our app. Assign the following values: ‘Response Types’ – select “Code” ‘Authentication Method’ – select “None” ‘Grant Types’ – select “Authorization Code” Enable the “Refresh Token” option.
Go to the 'Token Settings' section. Assign the following values: 'Auth Token Type' – select "JWT" Check all available boxes – "Add user roles to the access token", "User roles inside ID Token", "User info inside ID Token" 'ClockSkew' – set to approximately 20% to handle possible time differences between the server and the client Click the "Save" button to save the changes.
In the 'Redirect Settings' section, you can see the URLs assigned when creating the application. You can change these URLs or add new ones. Add a new redirect for the web app with the extension /#/callback, for example: http://localhost:4200/#/callback Click the "Save" button.
Project Configuration
Return to your project. Scroll down in the 'General’ section.
Check all the boxes and save the changes by clicking the "Save" button.

Creating Basic Roles

Create the basic roles for Mifos.

In the left-hand section, select 'Roles' and click the "New" button.
Fill in the fields as follows: Key = "1" Display Name = "Super user" Group = "This role provides all application permissions” Save the changes by clicking the "Save" button. This role (1) will be assigned to the admin user later.
Following the same process, use the following data: Key = "2" Display Name = "Self Service User" Group = "self service user role" Save the changes by clicking the "Save" button.
Project Grants Configuration
Go to the 'Grants' section. Add a new one by clicking the "New" button.
Select an 'organization' from the dropdown menu. Click the "Continue" button.
For now, no roles will be added to users. Click the "Save" button.
Verify that the grant is created and marked as "Active".
Switch to the "Authorization" section. Select the user 'ZITADEL Admin'. Assign the role "1" (previously created). Click the "Save" button. This will generate a "grant" version of the project.
To exit to the 'projects' section.
Select the 'Granted Projects' section. Open the project.
Here, you can view the "Resource id" and "Grant id". They will be used in the following steps of this manual.
User Service Configuration
Go to the "Users" tab. Select the "service Users" option.
Here, create a new service user by clicking "New".
Set the 'username', 'name', and 'Description' as desired. For 'Access Token Type', select "Bearer". Create the user by clicking "Create".
ZITADEL will display the data of the created user.
Configure Instance Authorizations
Go to the 'Authorizations' section and create one by clicking the "New" button.
ZITADEL will provide this by displaying an options box for the user and project. Select the service user created in the previous steps. Select the 'Grant' project. Click the "Continue" button.
Once the user is created, it must be marked as "active".
Click the three dots. Select "Show user".
Click the "Actions" button. Select the "Generate Client Secret" option.
This is the "ClientId" and "ClientSecret" for the service user.
Return to the main menu and click the "Default settings" button at the top right.
From the left-hand panel, select the "Login Behavior and Security" option.