Интеграция

Пакеты для .NET (NuGet)

Интеграция сервисов на .NET с помощью публичных NuGet-пакетов Cyberzone.Julia.Contracts и Cyberzone.Julia.Authorization.

Для сервисов на .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 и корректно работает с анонимными запросами.