برنامه نویسی

پیکربندی API های .NET با KeyCloak

Keycloak یک هویت آزاد و منبع باز و مدیریت دسترسی است که توسط Red Hat حمایت مالی می شود ، که تضمین برنامه های مدرن با ویژگی هایی مانند ورود به سیستم تک (SSO) و کارگزاری هویت. قابلیت های تأیید اعتبار و مجوز متمرکز آن ، همراه با فدراسیون کاربر و پشتیبانی چند اجاره ، آن را به ابزاری همه کاره برای مدیریت دسترسی کاربر در سیستم عامل های مختلف تبدیل می کند. در این مقاله ، من شما را از طریق پیکربندی یک .NET API با KeyCloak ، همه در حال اجرا روی Docker ، راهنمایی می کنم تا یک محیط امن و مقیاس پذیر ایجاد شود.

برای موارد کاربردی ساده تر ، کاوش در مجوزهای داخلی و مجوز داخلی NET با استفاده از هویت .NET ، همانطور که در برخی از مقالات قبلی من پوشش داده شده است ، ممکن است کافی باشد و ارزش در نظر گرفتن آن را داشته باشد. این رویکردهای بنیادی می تواند امنیت لازم را برای بسیاری از برنامه ها بدون نیاز به راه حل های پیچیده تر مانند KeyCloak فراهم کند. با این حال ، با افزایش نیازهای برنامه شما ، ادغام KeyCloak می تواند انعطاف پذیری و مقیاس پذیری پیشرفته را ارائه دهد.

این مقاله شامل موارد زیر است:

  1. راه اندازی پروژه اولیه
  2. فایل آهنگسازی Docker
  3. پیکربندی سرور KeyCloack
  4. ایمن کردن API .NET با Keycloack

برای این آموزش من از .NET 9 ، KeyCloak نسخه 26.1.0 و نسخه Postgres 17.4 استفاده می کنم.

برای راه اندازی اولیه ، تنها کاری که باید انجام دهید ایجاد یک برنامه کاربردی معمولی API .NET با پیش فرض است WeatherForecastController و با پیش فرض Dockerfileبشر شما Dockerfileباید چیزی شبیه به این باشد:

# This stage is used when running from VS in fast mode (Default for Debug configuration)
FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 80
EXPOSE 443

# This stage is used to build the service project
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["ReactApp.Server.csproj", "."]
RUN dotnet restore "./ReactApp.Server.csproj"
COPY . .
WORKDIR "/src/."
RUN dotnet build "./ReactApp.Server.csproj" -c $BUILD_CONFIGURATION -o /app/build

# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
ARG BUILD_CONFIGURATION=Release
RUN dotnet publish "./ReactApp.Server.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

# This stage is used in production or when running from VS in regular mode (Default when not using the Debug configuration)
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "ReactApp.Server.dll"]
حالت تمام صفحه را وارد کنید

از حالت تمام صفحه خارج شوید

اکنون که پروژه را تنظیم کرده اید ، باید موارد زیر را اضافه کنید docker compose پرونده:

version: '3.9'

services:
  backend:
    build:  
      context: ReactApp.Server
      dockerfile: Dockerfile
    ports:
      - "5080:80"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ASPNETCORE_HTTP_PORTS=80
    depends_on:
      - keycloak
    networks:
      - app-network

  keycloak:
    image: quay.io/keycloak/keycloak:26.1.0
    command: start-dev
    environment:
        KC_DB: postgres
        KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
        KC_DB_USERNAME: keycloak
        KC_DB_PASSWORD: password
        KC_BOOTSTRAP_ADMIN_USERNAME: admin
        KC_BOOTSTRAP_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    networks:
      - app-network

  postgres:
    image: postgres:17.4
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password

    ports:
      - "5432:5432"

    volumes:
      - postgres_data_keycloack:/var/lib/postgresql/data
    networks:
      - app-network

volumes:
  postgres_data_keycloack:

networks:
  app-network:
    driver: bridge
حالت تمام صفحه را وارد کنید

از حالت تمام صفحه خارج شوید

این پرونده docker خود توضیحی است. این پیکربندی برای سه سرویس دارد: سرویس پس زمینه در پورت 5080، سرویس KeyCloak در بندر 8080، و پایگاه داده PostgreSQL برای ذخیره داده های KeyCloak در پورت 5432بشر هر سه سرویس از app-network برای برقراری ارتباط ، و بانک اطلاعاتی از یک جلد برای ذخیره سازی مداوم داده ها استفاده می کند.

برای اجرای این پیکربندی ، از دستور زیر استفاده کنید:

docker compose up --build
حالت تمام صفحه را وارد کنید

از حالت تمام صفحه خارج شوید

اگر همه چیز به درستی تنظیم شده است ، باید بتوانید به آن بروید http://localhost:8080/ و به صفحه ورود به رابط مدیریت KeyCloak مراجعه کنید.

شرح تصویر

می توانید با استفاده از username وت password تعریف شده در پرونده آهنگسازی Docker. در این حالت ، این است adminبرای نام کاربری و رمز عبور.

متوجه خواهید شد که کنسول مدیریت KeyCloak تنظیمات بسیاری را ارائه می دهد که می توانند بر اساس مورد استفاده شما تنظیم شوند. با این حال ، برای حفظ این آموزش ، من فقط روی پیکربندی اصلی تمرکز خواهم کرد.

مرحله 1 – یک قلمرو ایجاد کنید

پس از ورود به سیستم ، باید یک قلمرو ایجاد کنید. قلمرو یک دامنه امنیتی است که مجموعه ای از کاربران ، اعتبارنامه ها ، نقش ها و گروه ها را مدیریت می کند و بین برنامه ها یا خدمات مختلف انزوا می کند. در مورد من ، من از قلمرو پیش فرض استفاده می کنم – masterبشر

مرحله 2 – ایجاد مشتری

برای اینکه یک برنامه بتواند از خدمات KeyCloaks مانند مجوز ، احراز هویت و موارد دیگر استفاده کند ، ابتدا باید در سرویس KeyCloak ثبت شود. این کار را می توان با ایجاد یک مشتری جدید انجام داد.

رفتن به مشتری کلیک بر روی مشتری ایجاد کنید و تنظیمات زیر را اضافه کنید:

شرح تصویر

تأیید اعتبار مشتری باید از آنجا که این سرویس خصوصی است فعال شود. برای خدمات عمومی باید غیرفعال شود. در این حالت ، از Standard flow برای تأیید اعتبار – جریان معمولاً برای برنامه های وب استفاده می شود. جریان های دیگر موارد استفاده متفاوتی را ارائه می دهند. اگر به موارد استفاده خاص برای هر جریان علاقه دارید ، من یک جدول با توضیحات مختصر در پیوست در پایان این مقاله گنجانده ام.

شرح تصویر

از آنجا که این یک برنامه پس زمینه است ، دیگر نیازی به اضافه کردن چیزی در آن نیست Login Settings بخش

مرحله 1 – پیکربندی KeyCloack را اضافه کنید

شما ابتدا برای نصب nuget pacakge زیر نیاز دارید:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
حالت تمام صفحه را وارد کنید

از حالت تمام صفحه خارج شوید

در Program.csپیکربندی زیر را اضافه کنید (توجه داشته باشید که keycloak:8080 برای شناسایی سرویس ، همانطور که با آهنگسازی Docker اجرا می شود استفاده می شود):

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "http://keycloak:8080/realms/master";
        options.RequireHttpsMetadata = false; // Only for develop
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = "http://localhost:8080/realms/master",
            ValidateAudience = true,
            ValidAudience = "net-web-api",
        };
);
حالت تمام صفحه را وارد کنید

از حالت تمام صفحه خارج شوید

فراموش نکنید که میانه های مناسب را نیز اضافه کنید:

app.UseAuthentication();
app.UseAuthorization();
حالت تمام صفحه را وارد کنید

از حالت تمام صفحه خارج شوید

و در آخر اضافه کردن [Authorize] ویژگی در WeatherForecastController:

[Authorize]
[ApiController]
[Route("/api/[controller]")]
public class WeatherForecastController : ControllerBase
حالت تمام صفحه را وارد کنید

از حالت تمام صفحه خارج شوید

مرحله 2 – مجوز آزمایش

در پیکربندی .NET API ، فیلدی به نام وجود دارد ValidAudience="net-web-api"، این بدان معنی است که فقط در صورتی که نشانه دسترسی حاوی مخاطب باشد net-web-apiدسترسی به منابع مجاز خواهد بود. برای فعال کردن این امر ، ما باید یک نقشه برداری ایجاد کنیم. رفتن به net-api-client پیکربندی ، سپس به سمت حرکت کنید دامنه مشتری، انتخاب کنید net-web-api-dedicated دامنه ، و نقشه برداری زیر را از نوع ایجاد کنید مخاطبان:

شرح تصویر

اکنون ، یک نشانه دسترسی از نقطه پایانی زیر را بدست آورید تا بتوانید مجوز را آزمایش کنید:

curl --location 'http://localhost:8080/realms/master/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=net-web-api' \
--data-urlencode 'client_secret=HXduWLurrenfHLadKG71P1GbUKH2HG04' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=net-web-api'
حالت تمام صفحه را وارد کنید

از حالت تمام صفحه خارج شوید

در client_secret می توان در اعتبار برگه net-web-api مشتری در داخل کنسول مدیریت.

شرح تصویر

در آخر ، از نشانه ای که قبلاً به دست آمده است استفاده کنید تا با آنها تماس بگیرید weatherforecast نقطه پایانی ، و شما باید بتوانید نتیجه را بدست آورید:

curl --location 'http://localhost:5080/api/weatherforecast' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJVTDlhN25Fc3kzb0RVMGFhSVdSM3pWYkNwdEdsVnZOMjhMMFprdUJBVXVrIn0.eyJleHAiOjE3NDAyNTI2NzYsImlhdCI6MTc0MDI1MjYxNiwianRpIjoiMzIwNDg1ODAtZjlkYS00MjAzLTgyZjUtMjlhN2Y3MWVhODFlIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL3JlYWxtcy9tYXN0ZXIiLCJhdWQiOlsibmV0LXdlYi1hcGkiLCJhY2NvdW50Il0sInN1YiI6ImUzNWUyZGNmLTJmOGQtNDkxMC1hNWNkLWFiNmJmZDE1MWNhMCIsInR5cCI6IkJlYXJlciIsImF6cCI6Im5ldC13ZWItYXBpIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyIvKiJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1tYXN0ZXIiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19LCJuZXQtd2ViLWFwaSI6eyJyb2xlcyI6WyJ1bWFfcHJvdGVjdGlvbiJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImNsaWVudEhvc3QiOiIxNzIuMTguMC4xIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtbmV0LXdlYi1hcGkiLCJjbGllbnRBZGRyZXNzIjoiMTcyLjE4LjAuMSIsImNsaWVudF9pZCI6Im5ldC13ZWItYXBpIn0.Dv0u_z25t7YRrrCBtjjM6ETbmm7HuM2oAly3RBCpNFKMvellMieimFwUHfMIiKt0Ju6JUqr8KpTfX1aekBMSkRwcBDGTgs-TMByn-mNSawbTay1WAvrwYnSPPqgk4TJolmzFooNt-zw4uHAfBmf_Lg5KAwtM6_q2vTbUJmOUbUK-KupdwfT9q9poQ_ckBcnGAz3o-xAIMcwfnmOFWzF6aINZ6ZPrD4FiFeRrzXP6JePdvfFds3O514nFt4exV1rkEDXQMDTr7fK03TYQxXOlNXwOyWJf102eMRGwBxy7SQyibB0O9bIPZWUzjuXMP2kQ6hC9T1p-PZvUTYNUSOQz1g'
حالت تمام صفحه را وارد کنید

از حالت تمام صفحه خارج شوید

شرح تصویر

در این مقاله ، من نحوه پیکربندی یک سرور KeyCloak را نشان داده ام و از آن برای ایمن سازی یک .NET API استفاده می کند. من قصد دارم مقاله دیگری بنویسم که در آن این مثال را با یک برنامه React ساده گسترش دهم. در مقاله زیر ، من به شما نشان می دهم که چگونه برنامه React Client را برای ادغام با API ایمن موجود و پیاده سازی عملکردهای اساسی مانند ورود به سیستم ، ورود به سیستم ، مشاهده داده های پروفایل کاربر و ترمیم استفاده از نشانه ها به شما نشان خواهم داد.

جریان شرح مورد استفاده
جریان استاندارد جریان کد مجوز OAUTH 2.0. کاربر از طریق KeyCloak ، کد مبادله مشتری برای نشانه ها وارد می شود. برنامه های وب با ذخیره سازی ایمن در سمت سرور.
کمک های مستقیم دسترسی مشتری نام کاربری/رمز عبور را برای دریافت مستقیم نشانه ها ارسال می کند. برنامه های قابل اعتماد (به عنوان مثال ، ابزار CLI ، سیستم های میراث).
جریان ضمنی توکن ها پس از ورود به سیستم (بدون مبادله کد) به طور مستقیم بازگردانده می شوند. برنامه های تک صفحه ای (SPA) یا برنامه های تلفن همراه (کمتر ایمن ، اکنون ناامید شده است).
نقش حساب های خدمات مشتری خود را (بدون کاربر) با استفاده از اعتبار مشتری برای دریافت نشانه ها تأیید می کند. سرویس های ماشین به ماشین (M2M) یا خدمات با پس زمینه.
کمک هزینه مجوز دستگاه کاربر از طریق یک کد در دستگاه دیگر یک دستگاه را مجاز می کند. دستگاه هایی با ورودی محدود (به عنوان مثال ، تلویزیون های هوشمند ، IoT).
Grant OIDC CIBA احراز هویت در یک دستگاه/کانال جداگانه بدون تعامل کاربر در مشتری اتفاق می افتد. سناریوهایی که تعامل کاربر امکان پذیر نیست (به عنوان مثال ، برنامه های بانکی ، IoT).

نوشته های مشابه

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

دکمه بازگشت به بالا