# jwt.net

**Repository Path**: nats-io/jwt.net

## Basic Information

- **Project Name**: jwt.net
- **Description**: JWT tokens signed using NKeys for Ed25519 for NATS .NET
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-03-14
- **Last Updated**: 2025-12-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NATS JWT .NET

[![License Apache 2.0](https://img.shields.io/badge/License-Apache2-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![NuGet](https://img.shields.io/nuget/v/NATS.Jwt.svg?cacheSeconds=3600)](https://www.nuget.org/packages/NATS.Jwt)
[![Build](https://github.com/nats-io/jwt.net/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/nats-io/jwt.net/actions/workflows/test.yml?query=branch%3Amain)
[![codecov](https://codecov.io/github/nats-io/jwt.net/graph/badge.svg?token=zXUTHG6L3Q)](https://codecov.io/github/nats-io/jwt.net)

**IMPORTANT**: This is a pre-release version of the library. The API is subject to change.

This is a .NET implementation of the JWT library for the NATS ecosystem.

> [!CAUTION]
> ### Important Disclaimer
>
> This repository provides an API to build NATS JWTs using .NET. However, at
> this time it is _not_ a supported API. Use at your own risk.
> 
> One important take away from this project is that the purpose of the library is
> for building JWTs, not to validate them exhaustively. This means that tokens
> generated by this library are expected to be validated by a process that uses
> the [NATS JWT Go library](github.com/nats-io/jwt). As that library is the one
> used by:
> 
> - [nats-server](github.com/nats-io/nats-server),
> - [nats-account-server](github.com/nats-io/nats-account-server)
> - [nsc](github.com/nats-io/nsc)
> 
> Under that context, ultimate validity of the JWT is delegated to tools or
> servers that use the [NATS JWT Go library](github.com/nats-io/jwt). Use of this
> library implies an agreement with the above disclaimer.

## TODO

- [x] Add public API analyzer
- [x] Remove No-warnings from build
- [x] Add more tests
- [x] Enable code coverage
- [ ] Add examples
- [ ] Add documentation

## Installation

You can install the package via NuGet:

```bash
dotnet add package NATS.Jwt --prerelease
```

## Usage

```csharp
// create an operator key pair (private key)
var okp = KeyPair.CreatePair(PrefixByte.Operator);
var opk = okp.GetPublicKey();

// create an operator claim using the public key for the identifier
var oc = NatsJwt.NewOperatorClaims(opk);
oc.Name = "Example Operator";

// add an operator signing key to sign accounts
var oskp = KeyPair.CreatePair(PrefixByte.Operator);
var ospk = oskp.GetPublicKey();

// add the signing key to the operator - this makes any account
// issued by the signing key to be valid for the operator
oc.Operator.SigningKeys = [ospk];

// self-sign the operator JWT - the operator trusts itself
var operatorJwt = NatsJwt.Encode(oc, okp);

// create an account keypair
var akp = KeyPair.CreatePair(PrefixByte.Account);
var apk = akp.GetPublicKey();

// create the claim for the account using the public key of the account
var ac = NatsJwt.NewAccountClaims(apk);
ac.Name = "Example Account";

var askp = KeyPair.CreatePair(PrefixByte.Account);
var aspk = askp.GetPublicKey();

// add the signing key (public) to the account
ac.Account.SigningKeys = [aspk];
var accountJwt = NatsJwt.Encode(ac, oskp);

// now back to the account, the account can issue users
// need not be known to the operator - the users are trusted
// because they will be signed by the account. The server will
// look up the account get a list of keys the account has and
// verify that the user was issued by one of those keys
var ukp = KeyPair.CreatePair(PrefixByte.User);
var upk = ukp.GetPublicKey();
var uc = NatsJwt.NewUserClaims(upk);

// since the jwt will be issued by a signing key, the issuer account
// must be set to the public ID of the account
uc.User.IssuerAccount = apk;
var userJwt = NatsJwt.Encode(uc, askp);

// the seed is a version of the keypair that is stored as text
var userSeed = ukp.GetSeed();

var conf = $$"""
             operator: {{operatorJwt}}

             resolver: MEMORY
             resolver_preload: {
                     {{apk}}: {{accountJwt}}
             }
             """;

// generate a creds formatted file that can be used by a NATS client
const string credsPath = $"example_user.creds";
File.WriteAllText(credsPath, NatsJwt.FormatUserConfig(userJwt, userSeed));

// now we are going to put it together into something that can be run
// we create a file to store the server configuration, the creds
// file and a small program that uses the creds file
const string confPath = $"example_server.conf";
File.WriteAllText(confPath, conf);

// run the server:
// > nats-server -c example_server.conf

// Connect as user
var authOpts = new NatsAuthOpts { CredsFile = credsPath };
var opts = new NatsOpts { Url = server.Url, AuthOpts = authOpts };
await using var nats = new NatsConnection(opts);
await nats.PingAsync();
```

## About

A [JWT](https://jwt.io/) implementation that uses [nkeys](https://github.com/nats-io/nkeys.net) to digitally sign
JWT tokens for the [NATS](https://nats.io/) ecosystem.

See also https://github.com/nats-io/jwt