Zitadel 6.1.0

.NET 6.0 This package targets .NET 6.0. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package Zitadel --version 6.1.0                

                    
                

            
NuGet\Install-Package Zitadel -Version 6.1.0
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="6.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add Zitadel --version 6.1.0                

                    
                

            
#r "nuget: Zitadel, 6.1.0"
#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=6.1.0

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

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 net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  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.2 626 11/13/2024
7.0.1 400 11/8/2024
7.0.0 1,080 10/28/2024
6.2.0 418 10/28/2024
6.1.4 96 10/28/2024
6.1.3 90 10/28/2024
6.1.2 44,272 1/31/2024
6.1.1 284 1/26/2024
6.1.0 692 1/26/2024
6.0.0 499 1/24/2024
5.3.3 6,175 1/10/2024
5.3.2 682 1/9/2024
5.3.1 1,963 1/3/2024
5.3.0 2,898 12/19/2023
5.2.26 12,855 10/4/2023
5.2.25 5,260 9/13/2023
5.2.24 720 9/8/2023
5.2.23 451 9/7/2023
5.2.22 392 9/7/2023
5.2.21 1,352 8/25/2023
5.2.20 1,763 8/19/2023
5.2.19 1,242 8/11/2023
5.2.18 993 8/9/2023
5.2.17 420 8/8/2023
5.2.16 2,081 7/17/2023
5.2.15 459 7/17/2023
5.2.14 611 7/11/2023
5.2.13 1,277 7/7/2023
5.2.12 525 7/5/2023
5.2.11 972 6/24/2023
5.2.10 448 6/23/2023
5.2.9 618 6/18/2023
5.2.8 7,091 5/27/2023
5.2.7 698 5/17/2023
5.2.6 587 5/9/2023
5.2.5 540 5/6/2023
5.2.4 524 5/5/2023
5.2.3 3,462 4/27/2023
5.2.2 615 4/22/2023
5.2.1 552 4/17/2023
5.2.0 686 4/14/2023
5.2.0-prerelease.3 83 4/14/2023
5.2.0-prerelease.2 82 4/14/2023
5.2.0-prerelease.1 87 4/13/2023
5.1.1 485 4/14/2023
5.1.0 502 4/13/2023
5.0.32 505 4/13/2023
5.0.31 467 4/12/2023
5.0.30 859 3/31/2023
5.0.29 564 3/26/2023
5.0.28 1,407 3/16/2023
5.0.27 582 3/15/2023
5.0.26 694 3/8/2023
5.0.25 945 3/3/2023
5.0.24 638 2/17/2023
5.0.23 553 2/16/2023
5.0.22 559 2/15/2023
5.0.21 582 2/15/2023
5.0.20 599 2/14/2023
5.0.19 618 2/10/2023
5.0.18 558 2/9/2023
5.0.17 581 2/8/2023
5.0.16 1,776 1/12/2023
5.0.15 599 1/11/2023
5.0.14 776 1/3/2023
5.0.13 689 12/16/2022
5.0.12 672 12/14/2022
5.0.11 639 12/8/2022
5.0.10 600 12/8/2022
5.0.9 691 12/3/2022
5.0.8 648 12/1/2022
5.0.7 820 11/18/2022
5.0.6 717 11/8/2022
5.0.5 768 10/27/2022
5.0.4 734 10/19/2022
5.0.3 738 10/17/2022
5.0.2 1,273 10/12/2022
5.0.1 723 10/6/2022
5.0.0 704 10/6/2022
4.0.12 749 9/30/2022
4.0.11 735 9/28/2022
4.0.10 763 9/27/2022
4.0.9 828 9/14/2022
4.0.8 833 9/2/2022
4.0.7 863 8/25/2022
4.0.6 761 8/19/2022
4.0.5 752 8/17/2022
4.0.4 753 8/10/2022
4.0.3 976 7/26/2022
4.0.2 856 7/22/2022
4.0.1 824 7/18/2022
4.0.0 798 7/18/2022
3.4.7 2,348 4/22/2022
3.4.6 1,026 4/20/2022
3.4.5 1,050 4/12/2022
3.4.4 1,044 4/1/2022
3.4.3 1,033 3/22/2022
3.4.2 1,076 3/8/2022
3.4.1 1,272 2/23/2022
3.4.0 980 2/23/2022
3.3.12 1,405 11/19/2021
3.3.11 1,037 11/8/2021
3.3.10 985 10/29/2021
3.3.9 949 10/26/2021
3.3.8 992 10/20/2021
3.3.7 996 10/19/2021
3.3.6 979 10/12/2021
3.3.5 1,004 10/11/2021
3.3.4 951 10/5/2021
3.3.3 1,013 9/30/2021
3.3.2 1,000 9/15/2021
3.3.1 934 9/14/2021
3.3.0 1,074 9/8/2021
3.2.3 947 9/7/2021
3.2.2 984 8/18/2021
3.2.1 957 8/13/2021
3.2.0 960 8/4/2021
3.1.8 1,090 6/22/2021
3.1.7 945 6/11/2021
3.1.6 2,872 6/8/2021
3.1.5 1,005 5/26/2021
3.1.4 873 5/25/2021
3.1.3 880 5/24/2021
3.1.2 907 5/13/2021
3.1.1 890 5/11/2021
3.1.0 945 5/7/2021
3.0.3 922 5/7/2021
3.0.2 970 5/1/2021
3.0.1 897 4/21/2021
3.0.0 901 4/16/2021
2.2.6 986 4/13/2021
2.2.5 920 4/9/2021
2.2.4 967 4/8/2021
2.2.3 982 4/6/2021
2.2.2 859 4/2/2021
2.2.1 916 4/1/2021
2.2.0 874 3/30/2021
2.1.2 1,002 3/25/2021
2.1.1 874 3/25/2021
2.1.0 672 3/25/2021
2.0.0 767 3/8/2021
1.2.0 1,030 1/14/2021
1.1.0 774 1/11/2021
1.0.0 886 12/18/2020

'# [6.1.0](https://github.com/smartive/zitadel-net/compare/v6.0.0...v6.1.0) (2024-01-26)


### Features

* add v2 beta clients from gRPC ([#918](https://github.com/smartive/zitadel-net/issues/918)) ([7ede9c3](https://github.com/smartive/zitadel-net/commit/7ede9c3c68505322c8fa008bfcaf6393cc3875fd))



'