Zitadel 7.0.9

dotnet add package Zitadel --version 7.0.9                
NuGet\Install-Package Zitadel -Version 7.0.9                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Zitadel" Version="7.0.9" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Zitadel --version 7.0.9                
#r "nuget: Zitadel, 7.0.9"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Zitadel as a Cake Addin
#addin nuget:?package=Zitadel&version=7.0.9

// Install Zitadel as a Cake Tool
#tool nuget:?package=Zitadel&version=7.0.9                

ZITADEL

The ZITADEL.net library is a collection of tools for building web applications. It supports easy access to the ZITADEL API as well as authentication handlers for .NET web applications and web APIs.

Credentials

There are three credentials that help with the access to ZITADEL:

  • "Application": used in web APIs to authenticate the relying party
  • "BasicAuthentication": creating normal basic auth credentials
  • "ServiceAccount": loads a service account json and authenticates against ZITADEL

The application supports creating a signed JWT token on behalf of the application:

var application = Application.LoadFromJsonString(
@"{
  ""type"": ""application"",
  ""keyId"": ""keyid"",
  ""key"": ""RSA KEY"",
  ""appId"": ""appid"",
  ""clientId"": ""client id""
}");
var jwt = await application.GetSignedJwtAsync("issuer");

The service account allows you to load a service account json and authenticate against ZITADEL to fetch a valid access token:

var serviceAccount = ServiceAccount.LoadFromJsonString(
@"{
  ""type"": ""serviceaccount"",
  ""keyId"": ""key id"",
  ""key"": ""RSA KEY"",
  ""userId"": ""user id""
}");
var token = await serviceAccount.AuthenticateAsync();

Accessing the ZITADEL API

This package also provides the compiled proto files. The ZITADEL library provides helper functions to create the various clients to manage resources.

The ZITADEL API Reference describes the gRPC clients, calls, and how to use them.

As an example, one may use the AuthClient to fetch the user information.

With a personal access token of a service account

const string apiUrl = "https://zitadel-libraries-l8boqa.zitadel.cloud";
const string personalAccessToken = "TOKEN";
var client = Clients.AuthService(new(apiUrl, ITokenProvider.Static(personalAccessToken)));
var result = await client.GetMyUserAsync(new());
Console.WriteLine($"User: {result.User}");

With a service account JWT profile

const string apiProject = "PROJECT ID";
var serviceAccount = ServiceAccount.LoadFromJsonString(
@"{
  ""type"": ""serviceaccount"",
  ""keyId"": ""key id"",
  ""key"": ""RSA KEY"",
  ""userId"": ""user id""
}");
client = Clients.AuthService(
    new(
        apiUrl,
        ITokenProvider.ServiceAccount(
            apiUrl,
            serviceAccount,
            new(){ ApiAccess = true })));
result = await client.GetMyUserAsync(new());
Console.WriteLine($"User: {result.User}");

You can also create the clients by yourself:

var accessToken = "fetch it somehow";
var channel = GrpcChannel.ForAddress("https://my-zitadel-api.com");
var client = new AuthService.AuthServiceClient(channel);
var result = await client.GetMyUserAsync(
    new(),
    new Metadata { { "Authorization", $"Bearer {accessToken}" } });
Console.WriteLine($"User: {result.User}");

Authentication in Web Apps

To authenticate ASP.NET web applications, use the AddZitadel() extension method on the IAuthenticationBuilder. You will need an application on a ZITADEL instance and a client ID.

// -- snip --
builder.Services
    .AddAuthorization()
    .AddAuthentication(ZitadelDefaults.AuthenticationScheme)
    .AddZitadel(
        o =>
        {
            o.Authority = "https://zitadel-libraries-l8boqa.zitadel.cloud/";
            o.ClientId = "170088295403946241@library";
            o.SignInScheme = IdentityConstants.ExternalScheme;
        })
    .AddExternalCookie()
    .Configure(
        o =>
        {
            o.Cookie.HttpOnly = true;
            o.Cookie.IsEssential = true;
            o.Cookie.SameSite = SameSiteMode.None;
            o.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        });
// -- snip --

The example above allows an ASP.NET web application to authenticate against ZITADEL and use the external cookie scheme to store the access token in a secure cookie.

Authentication in Web APIs

Authenticating web APIs is similar to authenticating web apps. In contrast to a web application, the web API cannot hold a user session with an external application cookie. Instead, web APIs use the introspection endpoint of ZITADEL to fetch information about the presented access token (be it JWT or opaque token). The authentication mechanism is based on the OAuth2Introspection package of "IdentityModel".

In ZITADEL you may use two different authentication methods:

  • Basic Auth
  • JWT Profile

With basic auth, you need to use client_id and client_secret, and with JWT profile, a special json is generated for you, that is required to authenticate the web API against ZITADEL.

builder.Services
    .AddAuthorization()
    .AddAuthentication()
    .AddZitadelIntrospection(
        o =>
        {
            o.Authority = "https://zitadel-libraries-l8boqa.zitadel.cloud/";
            o.ClientId = "170102032621961473@library";
            o.ClientSecret = "KNkKW8nx3rlEKOeHNUcPx80tZTP1uZTjJESfdA3kMEK7urhX3ChFukTMQrtjvG70";
        });

The code above uses basic authentication. You need to be sure that your API application in ZITADEL is configured to use basic authentication.

Below, a JWT profile (application credential) is used to authenticate the web API. Note that the client id is no longer required. Using JWT profile is the recommended way to authenticate web APIs.

builder.Services
    .AddAuthorization()
    .AddAuthentication()
    .AddZitadelIntrospection(
        o =>
        {
            o.Authority = "https://zitadel-libraries-l8boqa.zitadel.cloud";
            o.JwtProfile = Application.LoadFromJsonString("YOUR APPLICATION JSON");
        });

Caching

The OAuth2Introspection supports caching of the access token for a configured amount of time. This reduces the load on the issuer and allows faster requests for the same token. To enable caching, you need to configure caching in the options of AddZitadelIntrospection and add an implementation of IDistributedCache.

Faking / Mocking local Authentication

To enable local development or testing without a real world ZITADEL instance, you may use the mocked authentication. It simply adds all provided claims to the constructed identity and lets all calls pass as "authenticated".

You may send a request with two special headers to overwrite the behaviour per request:

  • x-zitadel-fake-auth: If this header is set to "false", the request will return as "unauthenticated"
  • x-zitadel-fake-user-id: If this header is set, the value of the header will be user as user ID.

To enable the fake authentication, simply use the AddZitadelFake extension method:

builder.Services
    .AddAuthorization()
    .AddAuthentication()
    .AddZitadelFake(o =>
        {
            o.FakeZitadelId = "1337";
        });
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Zitadel:

Package Downloads
Zitadel.Api

The API library for Zitadel. Implemented with gRPC, it allows access to the API of any Zitadel instance (default: https://api.zitadel.ch).

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
7.0.9 304 12/18/2024
7.0.8 153 12/17/2024
7.0.7 457 12/15/2024
7.0.6 1,107 12/4/2024
7.0.5 443 12/1/2024
7.0.4 280 11/27/2024
7.0.3 747 11/21/2024
7.0.2 962 11/13/2024
7.0.1 444 11/8/2024
7.0.0 1,479 10/28/2024
6.2.0 437 10/28/2024
6.1.4 111 10/28/2024
6.1.3 103 10/28/2024
6.1.2 47,206 1/31/2024
6.1.1 289 1/26/2024
6.1.0 697 1/26/2024
6.0.0 507 1/24/2024
5.3.3 6,298 1/10/2024
5.3.2 688 1/9/2024
5.3.1 1,973 1/3/2024
5.3.0 3,024 12/19/2023
5.2.26 13,222 10/4/2023
5.2.25 5,268 9/13/2023
5.2.24 725 9/8/2023
5.2.23 457 9/7/2023
5.2.22 398 9/7/2023
5.2.21 1,358 8/25/2023
5.2.20 1,769 8/19/2023
5.2.19 1,248 8/11/2023
5.2.18 999 8/9/2023
5.2.17 426 8/8/2023
5.2.16 2,092 7/17/2023
5.2.15 465 7/17/2023
5.2.14 617 7/11/2023
5.2.13 1,282 7/7/2023
5.2.12 531 7/5/2023
5.2.11 978 6/24/2023
5.2.10 454 6/23/2023
5.2.9 624 6/18/2023
5.2.8 7,097 5/27/2023
5.2.7 704 5/17/2023
5.2.6 593 5/9/2023
5.2.5 546 5/6/2023
5.2.4 530 5/5/2023
5.2.3 3,470 4/27/2023
5.2.2 620 4/22/2023
5.2.1 557 4/17/2023
5.2.0 692 4/14/2023
5.2.0-prerelease.3 87 4/14/2023
5.2.0-prerelease.2 86 4/14/2023
5.2.0-prerelease.1 91 4/13/2023
5.1.1 491 4/14/2023
5.1.0 508 4/13/2023
5.0.32 511 4/13/2023
5.0.31 473 4/12/2023
5.0.30 865 3/31/2023
5.0.29 572 3/26/2023
5.0.28 1,413 3/16/2023
5.0.27 588 3/15/2023
5.0.26 700 3/8/2023
5.0.25 951 3/3/2023
5.0.24 646 2/17/2023
5.0.23 559 2/16/2023
5.0.22 565 2/15/2023
5.0.21 588 2/15/2023
5.0.20 609 2/14/2023
5.0.19 626 2/10/2023
5.0.18 564 2/9/2023
5.0.17 587 2/8/2023
5.0.16 1,782 1/12/2023
5.0.15 607 1/11/2023
5.0.14 784 1/3/2023
5.0.13 697 12/16/2022
5.0.12 682 12/14/2022
5.0.11 644 12/8/2022
5.0.10 607 12/8/2022
5.0.9 697 12/3/2022
5.0.8 654 12/1/2022
5.0.7 825 11/18/2022
5.0.6 723 11/8/2022
5.0.5 774 10/27/2022
5.0.4 740 10/19/2022
5.0.3 744 10/17/2022
5.0.2 1,279 10/12/2022
5.0.1 730 10/6/2022
5.0.0 714 10/6/2022
4.0.12 755 9/30/2022
4.0.11 743 9/28/2022
4.0.10 773 9/27/2022
4.0.9 836 9/14/2022
4.0.8 843 9/2/2022
4.0.7 869 8/25/2022
4.0.6 766 8/19/2022
4.0.5 758 8/17/2022
4.0.4 758 8/10/2022
4.0.3 986 7/26/2022
4.0.2 862 7/22/2022
4.0.1 830 7/18/2022
4.0.0 804 7/18/2022
3.4.7 2,360 4/22/2022
3.4.6 1,035 4/20/2022
3.4.5 1,056 4/12/2022
3.4.4 1,050 4/1/2022
3.4.3 1,039 3/22/2022
3.4.2 1,082 3/8/2022
3.4.1 1,278 2/23/2022
3.4.0 986 2/23/2022
3.3.12 1,415 11/19/2021
3.3.11 1,045 11/8/2021
3.3.10 993 10/29/2021
3.3.9 957 10/26/2021
3.3.8 1,000 10/20/2021
3.3.7 1,004 10/19/2021
3.3.6 987 10/12/2021
3.3.5 1,012 10/11/2021
3.3.4 961 10/5/2021
3.3.3 1,020 9/30/2021
3.3.2 1,008 9/15/2021
3.3.1 942 9/14/2021
3.3.0 1,082 9/8/2021
3.2.3 955 9/7/2021
3.2.2 994 8/18/2021
3.2.1 965 8/13/2021
3.2.0 968 8/4/2021
3.1.8 1,098 6/22/2021
3.1.7 953 6/11/2021
3.1.6 2,880 6/8/2021
3.1.5 1,013 5/26/2021
3.1.4 881 5/25/2021
3.1.3 888 5/24/2021
3.1.2 915 5/13/2021
3.1.1 898 5/11/2021
3.1.0 953 5/7/2021
3.0.3 930 5/7/2021
3.0.2 977 5/1/2021
3.0.1 905 4/21/2021
3.0.0 909 4/16/2021
2.2.6 993 4/13/2021
2.2.5 928 4/9/2021
2.2.4 977 4/8/2021
2.2.3 990 4/6/2021
2.2.2 867 4/2/2021
2.2.1 924 4/1/2021
2.2.0 881 3/30/2021
2.1.2 1,010 3/25/2021
2.1.1 881 3/25/2021
2.1.0 682 3/25/2021
2.0.0 775 3/8/2021
1.2.0 1,038 1/14/2021
1.1.0 782 1/11/2021
1.0.0 896 12/18/2020