Пакеты для .NET (NuGet)
Для сервисов на .NET (8.0+) публикуются два официальных NuGet-пакета, покрывающих все задачи интеграции: gRPC-контракты, валидацию EdDSA JWT, работу с моделью JuliaPrincipal, проверку прав и парсинг API-ключей.
| Пакет | Назначение |
|---|---|
Cyberzone.Julia.Contracts | Сгенерированные gRPC-клиенты и .proto-контракты + поддержка EdDSA (Ed25519) для Microsoft.IdentityModel.Tokens |
Cyberzone.Julia.Authorization | Типизированная модель субъекта JuliaPrincipal, иерархическая проверка прав, фильтры Minimal API, gRPC PermissionInterceptor и валидатор ApiKey |
Установка
dotnet add package Cyberzone.Julia.Contracts
dotnet add package Cyberzone.Julia.Authorization
Cyberzone.Julia.Contracts
Пакет состоит из двух независимых частей: gRPC-клиентов (плюс исходные .proto-файлы в каталоге protos/ пакета) и криптографии EdDSA.
Валидация JWT с помощью EdDsaSecurityKey
Стандартная библиотека Microsoft.IdentityModel.Tokens не поддерживает Ed25519 из коробки. EdDsaSecurityKey автоматически регистрирует свой CryptoProviderFactory и работает с TokenValidationParameters как обычный ключ:
using Cyberzone.Julia.Contracts.Crypto;
using Cyberzone.Julia.Contracts.Crypto.EdDsa;
using Microsoft.IdentityModel.Tokens;
// Из REST /v1/auth/publickey?type=base64 или gRPC Keys.GetPublicKey:
var key = new EdDsaSecurityKey(Convert.FromBase64String(publicKeyBase64));
// Либо из JWKS (/.well-known/jwks.json):
// var key = new EdDsaSecurityKey(Base64UrlEncoder.DecodeBytes(jwk.X));
options.MapInboundClaims = false;
options.TokenValidationParameters = new TokenValidationParameters
{
ValidAlgorithms = [ExtendedSecurityAlgorithms.EdDsa],
ValidIssuer = issuer,
ValidAudience = audience,
ValidateLifetime = true,
IssuerSigningKeyResolver = (_, _, kid, _) =>
string.IsNullOrEmpty(kid) || kid == key.KeyId ? [key] : [],
};
MapInboundClaims = false при настройке JwtBearerOptions. Иначе ASP.NET Core переименует claim sub, и разбор JuliaPrincipal не сработает.Генерация тестовых токенов
В интеграционных тестах вашего сервиса удобно выпускать тестовые EdDSA-токены через EdDsaSecurityKeyProvider:
using System.IdentityModel.Tokens.Jwt;
using Cyberzone.Julia.Contracts.Crypto;
using Cyberzone.Julia.Contracts.Crypto.EdDsa;
using Microsoft.IdentityModel.Tokens;
using var keys = new EdDsaSecurityKeyProvider();
var credentials = new SigningCredentials(keys.GetSecurityKey(), ExtendedSecurityAlgorithms.EdDsa);
var jwt = new JwtSecurityTokenHandler().WriteToken(new JwtSecurityToken(
issuer,
audience,
claims,
expires: DateTime.UtcNow.AddMinutes(15),
signingCredentials: credentials));
Cyberzone.Julia.Authorization
Пакет предоставляет единую модель субъекта и проверку прав формата base:operation:scope для ASP.NET Core Minimal API и gRPC.
1. Регистрация и провайдер прав
Реализуйте IPermissionProvider и зарегистрируйте авторизацию в DI:
using Cyberzone.Julia.Authorization.Abstractions;
using Cyberzone.Julia.Authorization.Extensions;
using Cyberzone.Julia.Authorization.Interceptors;
using Cyberzone.Julia.Authorization.Models;
builder.Services.AddJuliaAuthorization<PermissionProvider>();
builder.Services.AddGrpc(o => o.Interceptors.Add<PermissionInterceptor>()); // если используете gRPC
public sealed class PermissionProvider : IPermissionProvider
{
public async Task<IEnumerable<string>> GetSubjectPermissionsAsync(JuliaPrincipal subject)
{
// API-ключи и сервисные субъекты уже несут эффективные права
if (subject.IsApiKey || subject.IsMachine)
return subject.EmbeddedPermissions ?? [];
// Для пользователей загрузите и закешируйте права из Julia
return await LoadUserPermissionsAsync(subject.SubjectId);
}
}
2. Обёртка JuliaClaimsPrincipal в обработчиках аутентификации
Оберните ClaimsPrincipal в JuliaClaimsPrincipal один раз на этапе аутентификации, чтобы фильтры и обработчики не перечитывали клеймы повторно:
using Cyberzone.Julia.Authorization;
using Cyberzone.Julia.Authorization.Models;
// В JwtBearerEvents:
OnTokenValidated = context =>
{
if (JuliaClaimsPrincipal.TryWrap(context.Principal!, out var wrapped))
context.Principal = wrapped;
return Task.CompletedTask;
};
// В собственном обработчике API-ключей:
if (!ApiKey.TryParse(presentedKey, out var reference))
return AuthenticateResult.Fail("Invalid API key");
var subject = await IntrospectAsync(presentedKey, remoteIp);
return AuthenticateResult.Success(new AuthenticationTicket(
JuliaClaimsPrincipal.Issue(subject, Scheme.Name), Scheme.Name));
ApiKey.ComputeHash(presentedKey) (и IP-адрес клиента при ip_unrestricted == false), но никогда не кешируйте по reference.TokenId. Для отображения и логов используйте ApiKey.Hint(presentedKey).3. Защита эндпоинтов (Minimal API и gRPC)
// Minimal API:
app.MapGet("/api/v1/items", GetItems)
.RequirePermission("myservice.items:read"); // требуются все перечисленные
app.MapGet("/api/v1/stats", GetStats)
.RequireAnyPermission("myservice.stats:read", "myservice.admin"); // достаточно любого
// gRPC-сервис (требует подключённый PermissionInterceptor):
[RequirePermission("myservice.items:read")]
public override Task<ItemResponse> GetItem(ItemRequest request, ServerCallContext context)
При отказе возвращается 401 / 403 в HTTP и Unauthenticated / PermissionDenied в gRPC. Если настроить PermissionFilterOptions.UseExceptions, фильтры выбрасывают UnauthorizedAccessException / ForbiddenException для вашего exception middleware.
4. Проверка доступа к ресурсу конкретного пользователя
Когда в маршруте есть {uuid} целевого пользователя, используйте RequirePermissionInAnyScope на маршруте и AuthorizationHelper.CanAccessUserResourceAsync в обработчике:
app.MapGet("/api/v1/users/{uuid:guid}/orders", async (
Guid uuid, HttpContext http, IPermissionProvider permissions) =>
{
var subject = http.User.ToJuliaPrincipal();
// Пропускает владельца (subject.SubjectId == uuid) либо носителя глобального/делегированного права
if (!await AuthorizationHelper.CanAccessUserResourceAsync(
permissions, subject, uuid, "myservice.orders:read",
new HttpPermissionContext(http)))
return Results.Forbid();
return Results.Ok(await LoadOrdersAsync(uuid));
})
.RequirePermissionInAnyScope("myservice.orders:read");
Если эндпоинт доступен публично и меняет объём ответа в зависимости от вызывающего (как профили в Julia), используйте httpContext.ResolveAccessLevelAsync(...) — он возвращает ResourceAccessLevel.Public, Owner или Privileged и корректно работает с анонимными запросами.
Отделы (Departments)
Иерархия отделов, slug, системные и кастомные роли, старшинство, правила видимости и справочник кодов ошибок.
Пакет Go
Интеграция сервисов на Go (1.25+) с помощью официального модуля git.cyberzone.dev/cyberzone/julia-go — проверка EdDSA JWT, права, HTTP/gRPC middleware и API-ключи.