Feijuca.Keycloak.MultiTenancy 1.7.0

WIP

Built With

<img src="https://img.shields.io/badge/dotnet8-blue" />

Prerequisites 📋

This project was made with the purpose to attend only applications that follows the current .Net Supported versions.

Why Feijuca 🫘?

Feijuca is a nickname for a famous Brazilian dish called Feijoada. I wanted to use a name representing my country on this project and Feijuca was chosen.

About the project🧾

This repository aims to provide a configuration option for .NET projects that are using or planning to use Keycloak for authentication and JWT token generation. The project consists of two distinct parts:

1. Feijuca.Keycloak.Auth.MultiTenancy
2. Feijuca.Keycloak.TokenManager

Attention: 🫵

• The projects work in isolation way, there is no dependency between them. You do not need use one to use other, note that each project has different purpose, below you can understand better:

Feijuca.Keycloak.Auth.MultiTenancy 👨🏽‍💻

A NuGet package that enables the implementation of multi-tenancy concepts using Keycloak. Each realm in Keycloak can represent a different tenant, allowing for unique configurations for each one. This ensures that each tenant within your application can have its own settings within Keycloak.

Features ⛲

• You can use all existings keycloak features following a multi tenancy concept based on your realms, so you can handle different configurations based on each tenant (realm).
• With just one instance from your application you can handle different tenants using the same JWT token generation config
• Obtaining information such as a tenant, user id, url and so on from a token. (If you wanna implement a method do retrieve another thing related to the token, open a PR)

Feijuca.Keycloak.TokenManager 👨🏽‍💻

Managing certain actions in Keycloak can be complicated. For instance, creating a new user using the keycloak api involves several steps: obtaining a token, creating the user, setting a password... With Feijuca.Keycloak.TokenManager, you can create a user in a single request since all necessary actions are already integrated into the project.

Features ⛲

• Every action in one place. Forget about call multiples endpoints to do actions about users on keycloak. Do actions related to the user (Creation, remotion, e-mail confirming, password redefinition, and so on) based on predefined endpoints.
• Custom endpoints based on your necessities (If you think it could be helpful to the project, open a PR to discuss additional features).

Getting Started - Multi tenancy configuration

• Prerequisites It is assumed that you already have your Keycloak instance configured, including the creation of clients with their respective settings (scopes, etc.).

• Keycloak configuration steps:

  • 1. Storing the Tenant in the User Attribute: Each user should have an attribute that indicates which tenant they belong to. The value of this attribute should be the name of the corresponding realm. It can be a number or a string, according to your preference.
  • 2. Creating the Attribute: You can create this attribute manually in Keycloak or use Feijuca.Keycloak.TokenManager to create new users with this default attribute.
       
  • 3. Audience: Create a new audience related to the scopes used your client and include the audience on your client: This step is important and mandatory because on each request received the tool will confirm the token audience following what was filled out on step 3.

• Project configurations steps:

  • 4. Appsettings.json Filled out appsettings file on your application, relate all of yours realms (tenants)

    {
       "AuthSettings": {
          "Realms": [
             {
                "Name": "yourTenantName1",
                "Audience": "your-audience",
                "Issuer": "https://url-keycloakt/realms/yourTenantName1"
             },
             {
                "Name": "yourTenantName2",
                "Audience": "your-audience",
                "Issuer": "https://url-keycloakt/realms/yourTenantName2"
             },
             {
                "Name": "yourTenantName3",
                "Audience": "documents-processor-api",
                "Issuer": "https://url-keycloakt/realms/yourTenantName3"
             }
       ],
       "ClientSecret": "your-client-secret",
       "ClientId": "your-client-id",
       "Resource": "your-client-id",
       "AuthServerUrl": "https://url-keycloak"
       }
    }
    

• 5. Configure dependency Map appsettings configurations values (Note that AuthSettings is a model defined on Feijuca.Keycloak.Auth.MultiTenancy, I recommend you use the GetSection method to map the appsettings configs to the AuthSettings model:

     var settings = configuration.GetSection("AuthSettings").Get<AuthSettings>();
     

     Add the service to the service collection from your application, I recommend you create a new extension method as below:

     builder.Services
      .AddApiAuthentication(applicationSettings.AuthSettings!);
     
     public static class AuthExtension
      {
          public static IServiceCollection AddApiAuthentication(this IServiceCollection services, AuthSettings authSettings)
          {
              services.AddHttpContextAccessor();
              services.AddSingleton<JwtSecurityTokenHandler>();
              services.AddKeyCloakAuth(authSettings!);
     
              return services;
          }
      }
     

• 6. Conclusion: Following a default example, after generated, your token should have the following details: Audience(s) related to the clients scopes:

  And your appsettings should be:

  "AuthSettings": {
      "Realms": [
        {
          "Name": "10000",
          "Audience": "receipts-commandhander-api",
          "Issuer": "https://url-keycloak/realms/10000"
        }
      ],
      "ClientId": "receipts-commandhander-api",
      "Resource": "receipts-commandhander-api",
      "AuthServerUrl": "https://url-keycloak",      
    }
  

  With this configuration you should be able to use Keycloak following a multi tenancy contenxt using .NET. Following this link you can understand what is the logic used to validate the token received.

Getting Started - Using Token Manager Api

If you wish use to accomplish the goal to use multi tenancy concept based on each realm on your keycloak instance, here is the steps to configure it:

1. Fill out the appsettings configs related to your realms (tenants)

   {
      "AuthSettings": {
         "Realms": [
            {
               "Name": "yourTenantName1",
               "Audience": "your-audience",
               "Issuer": "https://url-keycloakt/realms/yourTenantName1"
            },
            {
               "Name": "yourTenantName2",
               "Audience": "your-audience",
               "Issuer": "https://url-keycloakt/realms/yourTenantName2"
            },
            {
               "Name": "yourTenantName3",
               "Audience": "documents-processor-api",
               "Issuer": "https://url-keycloakt/realms/yourTenantName3"
            }
      ],
      "ClientSecret": "your-client-secret",
      "ClientId": "your-client-id",
      "Resource": "your-client-id",
      "AuthServerUrl": "https://url-keycloakt"
      }
   }
   

2. Configure dependency injection (Note that AuthSettings is a model defined on Feijuca.Keycloak.Auth.MultiTenancy, usually I mapped it to variable. for example:

   var settings = configuration.GetSection("AuthSettings").Get<AuthSettings>();
   
   builder.Services
    .AddApiAuthentication(applicationSettings.AuthSettings!);
   
   public static IServiceCollection AddApiAuthentication(this IServiceCollection services, AuthSettings authSettings)
   {
       services.AddHttpContextAccessor();
       services.AddSingleton<JwtSecurityTokenHandler>();
       services.AddKeyCloakAuth(authSettings!);
   
       return services;
   }
   

Contributing

This is a project in costant evolution, therefore, if you have some suggestion, enter in contact with me or open a pull request and we can discuss.

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact