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.

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

1. 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.

2. 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’.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.

8. 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.

Locate the 'Default Redirect URI' field (usually at the bottom of the page).

Add the URL of the Mifos Web App (the same one entered in point "c" of this manual).

In that text box, enter the login URL so that when verifying a user by email, they are redirected to our login instead of the ZITADEL console.

In the main console, in the 'Organization' section, click the "+" sign.

A dialog box will appear requesting a 'loginname'. Select the service user.

For permissions, select all options except "Self Management Global".

Click "Add". 

Note: DO NOT DELETE THE MAIN USER unless there is another user with the same authorizations. Doing so may prevent access to the ZITADEL console, making it impossible to make changes in the future and causing loss of configurations.

9. Download the ZITADEL Plugin for Fineract

You can download the latest compiled version of the JAR from JFrog.

https://mifos.jfrog.io/ui/native/libs-snapshot-local/community/mifos/mifos-security-plugin/1.12.0-SNAPSHOT/  

Move the JAR file to the Fineract plugins folder.

This folder is not configured by default. Check the docker-compose.yml file.

If a plugins folder is not configured, define it in the ‘environment’ section of Fineract, for example:

• ./<directory>/:/app/plugins/

Add or edit a similar line if needed.

10. Get Fineract Environment Variables

Get the environment variables.

Collect the environment variables in a separate file to simplify the process.

Backend variables: all data are examples and must be replaced with the values generated in the ZITADEL console.

FINERACT_PLUGIN_OIDC_FRONTEND_URL=http://localhost:4200 

-These values are provided by the first application created within our project (called "Backend_api" in this manual).

FINERACT_PLUGIN_OIDC_OPAQUETOKEN_CLIENT_ID=320912215601386953 

FINERACT_PLUGIN_OIDC_OPAQUETOKEN_CLIENT_SECRET=Oi6WQvgYw5XwfACyH3DQWi0jkF47mzS7ZUFy83uODqrQEDAK0wXr41vSDxPT0OTu 

FINERACT_SERVER_OAUTH_RESOURCE_URL=https://plugin-auth-ofrdfj.us1.zitadel.cloud 

-This value is provided by the second application created within the project (called "Frontend" in this manual).

FINERACT_PLUGIN_OIDC_WEBAPP_CLIENT_ID=321191693166683125 

-Obtain the "resource id" from the Grant project, which corresponds to "PROJECT_ID", and the "Grant_id", which corresponds to "PROJECT_GRANT_ID".

FINERACT_PLUGIN_OIDC_PROJECT_ID=320736469398325498 

FINERACT_PLUGIN_OIDC_PROJECT_GRANT_ID=320771922155544476 

-Obtain the following data from the service user: "CLIENT_ID" and "CLIENT_SECRET".

FINERACT_PLUGIN_OIDC_SERVICE_USER_CLIENT_ID=Asistente 

FINERACT_PLUGIN_OIDC_SERVICE_USER_CLIENT_SECRET=klug5LQYdGAHJuGPa5wFfQMN2d0fvjyAo6Q4hQJQctgcXS4q50qqolWHb54eUE1R 

11. Get WebApp Environment Variables

The variables are examples and must be replaced.

FINERACT_PLUGIN_OIDC_ENABLED=false 

When creating our first application, it will provide the "ISSUER" (page 16).

In this step, it is important to add a "/" at the end of the URL. 

export FINERACT_PLUGIN_OIDC_BASE_URL=https://plugin-auth-ofrdfj.us1.zitadel.cloud/ 

-This value is provided by the second application created within the project (called "Frontend" in this manual).

FINERACT_PLUGIN_OIDC_CLIENT_ID=321191693166683125 

-It is necessary to know which port the backend is running on..

FINERACT_PLUGIN_OIDC_API_URL=https://localhost:8443/fineract-provider/

• For the next variable add the web app URL:

FINERACT_PLUGIN_OIDC_FRONTEND_URL=http://localhost:4200/

12. Deploy Mifos X With the ZITADEL Plugin

Go to the folder where the 'docker-compose.yml' file of your implementation is located.

Modify the contents of the YML file. You can use a text editor such as VSCode.

To configure the Web App image, set:

image: openmf/web-app-zitadel:dev

The variables must be placed in the 'environment' section of the Web App:

• MIFOS_OAUTH_SERVER_ENABLED=fasle

• FINERACT_PLUGIN_OIDC_ENABLED=false

• FINERACT_PLUGIN_OIDC_BASE_URL

• FINERACT_PLUGIN_OIDC_CLIENT_ID

• FINERACT_PLUGIN_OIDC_API_URL

• FINERACT_PLUGIN_OIDC_FRONTEND_URL

In addition to the variables obtained from Zitadel, add the following variables in the ‘environment’ section of the fineract-server:

FINERACT_SECURITY_BASICAUTH_ENABLED=false

FINERACT_SECURITY_OAUTH_ENABLED=true

FINERACT_SECURITY_2FA_ENABLED=false

FINERACT_SECURITY_HSTS_ENABLED=false

FINERACT_PLUGIN_OIDC_CONCURRENT_SESSIONS=1

From the variables obtained from Zitadel, place them in the ‘environment’ section of the fineract-server:

FINERACT_PLUGIN_OIDC_FRONTEND_URL

FINERACT_PLUGIN_OIDC_PROJECT_ID

FINERACT_PLUGIN_OIDC_PROJECT_GRANT_ID

FINERACT_PLUGIN_OIDC_SERVICE_USER_CLIENT_ID

FINERACT_PLUGIN_OIDC_SERVICE_USER_CLIENT_SECRET

FINERACT_PLUGIN_OIDC_WEBAPP_CLIENT_ID

FINERACT_PLUGIN_OIDC_OPAQUETOKEN_CLIENT_ID

FINERACT_PLUGIN_OIDC_OPAQUETOKEN_CLIENT_SECRET

FINERACT_PLUGIN_OIDC_SIGNING_KEY

FINERACT_SERVER_OAUTH_RESOURCE_URL

Once the environment variables are exported, we can start our project.

Login to powershell as administrator

Go to the path where we have the docker-compose.yml file.

$ cd “<directory>”

Start the Docker Compose containers with the command:

$ docker compose up -d

Once the containers are initialized, they will be visible in the Docker application.

Review the Logs to validate that the containers were started correctly. Please be patient, it could take some minutes to complete.

When accessing the Mifos web, the changes made will be visible.

To log in, use the credentials of the administrator user from the ZITADEL console.

Version

Date

Subject

Author

Reviewer

1.0

15 - August - 2025

Mifos X - Windows configuration for OAuth with ZITADEL

Emanuel Castillo

Victor Romero