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

Keycloak یک هویت آزاد و منبع باز و مدیریت دسترسی است که توسط Red Hat حمایت مالی می شود ، که تضمین برنامه های مدرن با ویژگی هایی مانند ورود به سیستم تک (SSO) و کارگزاری هویت. قابلیت های تأیید اعتبار و مجوز متمرکز آن ، همراه با فدراسیون کاربر و پشتیبانی چند اجاره ، آن را به ابزاری همه کاره برای مدیریت دسترسی کاربر در سیستم عامل های مختلف تبدیل می کند. در این مقاله ، من شما را از طریق پیکربندی یک .NET API با KeyCloak ، همه در حال اجرا روی Docker ، راهنمایی می کنم تا یک محیط امن و مقیاس پذیر ایجاد شود.
برای موارد کاربردی ساده تر ، کاوش در مجوزهای داخلی و مجوز داخلی NET با استفاده از هویت .NET ، همانطور که در برخی از مقالات قبلی من پوشش داده شده است ، ممکن است کافی باشد و ارزش در نظر گرفتن آن را داشته باشد. این رویکردهای بنیادی می تواند امنیت لازم را برای بسیاری از برنامه ها بدون نیاز به راه حل های پیچیده تر مانند KeyCloak فراهم کند. با این حال ، با افزایش نیازهای برنامه شما ، ادغام KeyCloak می تواند انعطاف پذیری و مقیاس پذیری پیشرفته را ارائه دهد.
این مقاله شامل موارد زیر است:
- راه اندازی پروژه اولیه
- فایل آهنگسازی Docker
- پیکربندی سرور KeyCloack
- ایمن کردن 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). |