مجوز کارشناسی ارشد در Umbraco 14/15: چالش ها و راه حل های API مدیریت دنیای واقعی

Summarize this content to 400 words in Persian Lang
وقتی برای اولین بار کار با Umbraco's Management API را شروع کردم، هم هیجان زده و هم کنجکاو بودم. این API قابلیت های مدیریت بدون هد را نوید می دهد که می تواند واقعاً اتوماسیون و ادغام برنامه های سفارشی با باطن Umbraco را ارتقا دهد. اما مانند بسیاری از ابزارهای جدید، چالش واقعی زمانی پدیدار شد که من سعی کردم آن را فراتر از محیط‌های آزمایشی مستند اجرا کنم.

در این مقاله، درس‌هایی را که هنگام تلاش برای پیمایش در چشم‌انداز دشوار مجوز مدیریت API در تنظیمات محلی و تولیدی آموختم، به اشتراک می‌گذارم. چه یک توسعه‌دهنده باتجربه Umbraco باشید و چه تازه شروع به کار کرده‌اید، امیدوارم این به شما کمک کند تا نه تنها نحوه کارکردن کارها را درک کنید، بلکه به این کمک کند که چرا وضعیت فعلی اسناد می‌تواند آن را به چنین سفر دشواری تبدیل کند.

درک مجوز مدیریت API

مدیریت API یک تحول مهم برای Umbraco است که جایگزین کنترلرهای backoffice قبلی با رویکردی قوی تر و RESTful شده است. در حالی که عملکردهای اصلی آن به خوبی مستند شده است، فرآیند دریافت توکن های مجوز و مدیریت دسترسی ایمن خالی از اشکال نیست، به خصوص اگر به دنبال Swagger یا Postman باشید (https://docs.umbraco.com/umbraco-cms/) مرجع/مدیریت-api/پستمن-تنظیم-سوءگر).منبع: (https://docs.umbraco.com/umbraco-cms/reference/management-api)

اسناد Swagger برای مدیریت API عمدتاً در محیط‌های غیر تولیدی فعال می‌شود. این بدان معنی است که می توانید از آن به طور مؤثر برای اهداف آزمایشی استفاده کنید، از OAuth2 با PKCE در Postman یا خود Swagger استفاده کنید. با این حال، وقتی به یک محیط تولید نقل مکان می کنید، جایی که Swagger غیرفعال است، همه چیز به طور قابل توجهی چالش برانگیزتر می شود. فقط مشتری “umbraco-back-office” مجاز به تولید است، که نیاز به رسیدگی دقیق برای جلوگیری از درگیری و عدم پوشش اسناد دارد.

در مرحله تولید، Swagger در دسترس نیست، و مستندات شکاف‌های زیادی را برای توسعه‌دهندگانی که تلاش می‌کنند با OpenID Connect برقرار کنند، باقی می‌گذارد. فقط مشتری “umbraco-back-office” مجاز به اتصال است، در حالی که در حالت غیر تولیدی، می توانید از مشتریانی مانند “umbraco-swagger” یا “umbraco-postman” استفاده کنید. این رویکرد از منظر امنیتی قابل درک است، اما در هنگام راه‌اندازی ادغام‌های مشتری سفارشی یا تضمین گردش کار روان برای استقرار، موانعی را ایجاد می‌کند.

قطعات گمشده: مجوز محلی و تولید

اسناد فعلی ارائه شده توسط Umbraco برای راه اندازی اولیه در محیط های غیر تولیدی، با دستورالعمل های واضح در مورد استفاده از Postman برای اتصال یک کاربر backoffice از طریق OAuth2 مفید است. با این حال، اگر می‌خواهید این فرآیند مجوز را در یک محیط توسعه محلی یا – به طور جدی‌تر – در یک محیط تولید تکرار کنید، به سرعت خود را بدون نقشه می‌یابید. علاوه بر این، اسناد در حال حاضر کامل نیست و ممکن است بعداً توسط Umbraco HQ به‌روزرسانی شود، احتمالاً زمانی که آنها برنامه‌های دقیق‌تری برای مدیریت API داشته باشند، همانطور که اخیراً کاربران API را در Umbraco 15 معرفی کرده‌اند.

من اخیراً مجوز مدیریت API را در محیط‌های محلی و تولیدی تنظیم کردم، و مشخص شد که بسیاری از مراحل غیرمستند بوده یا نیاز به جمع‌آوری اطلاعات از بخش‌های مختلف جامعه Umbraco دارند. اسناد رسمی به شدت بر روی Swagger و Postman تمرکز دارد که برای آزمایش ایده آل است اما در هنگام کار با برنامه های کاربردی مشتری واقعی یا گردش کار سفارشی کاملاً کافی نیست.

به عنوان مثال، در محیط‌های محلی، برای کار روان OpenID Connect اغلب نیاز به تنظیم دستی تنظیمات برای همسویی با قوانین غیر تولید دارد. تنظیمات Swagger و Postman به طور پیش‌فرض از «umbraco-swagger» یا «umbraco-postman» به عنوان client_id استفاده می‌کنند که در زمینه‌های تولید محلی معتبر نیست. علاوه بر این، در تولید، تضمین دسترسی ایمن به معنای غواصی در جریان‌های OAuth2 بدون راز مشتری بود – چیزی که به صراحت برای اکثر سناریوهای محلی و تولیدی در اسناد پوشش داده نمی‌شود.

نقاط درد مجوز و راه حل

یکی از مسائل کلیدی که من با آن مواجه شدم، تلاش برای استفاده از کلاینت “umbraco-back-office” به عنوان شناسه مشتری بود. می‌توانید URL برگشت به تماس را در تنظیمات برنامه‌ها در Umbraco:CMS:Security:AuthorizeCallbackPathName مشخص کنید، اما یک مشکل مهم وجود دارد: backoffice Umbraco از همان کلاینت استفاده می‌کند، که منجر به برگشت تماس شکسته می‌شود و جریان ورود به بک آفیس را مختل می‌کند. علاوه بر این، این موضوع مستند نشده است، که عیب یابی را چالش برانگیزتر می کند.پس از بررسی این موضوع، بهترین رویکرد در حال حاضر، تمدید آن است OpenIdDictApplicationManagerBase و یک مشتری جدید ایجاد کنید. با انجام این کار، می توانید یک کلاینت اختصاصی برای ادغام خود بدون تداخل با کلاینت پیش فرض backoffice ایجاد کنید، بنابراین از تضاد جلوگیری می کنید.

appsetting.json

{
“BaseUrl”: “https://localhost:44329”,
“ClientId”: “newclientId”, // generated through /create-client
“AuthorizationEndpoint”: “/umbraco/management/api/v1/security/back-office/authorize”,
“TokenEndpoint”: “/umbraco/management/api/v1/security/back-office/token”,
“RedirectUri”: “https://localhost:44329/callback”
}

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

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

در اینجا یک نسخه ساده از تنظیمات من است که از Minimal API برای ایجاد یک مدیر برنامه سفارشی استفاده می کند:

using Microsoft.AspNetCore.Mvc;
using OpenIddict.Abstractions;
using OpenIddict.Core;
using UmbDemo14.Web;
using Microsoft.Extensions.Options;
using Umbraco.Cms.Api.Management.Security;
using Umbraco.Cms.Infrastructure.Security;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.CreateUmbracoBuilder()
.AddBackOffice()
.AddWebsite()
.AddDeliveryApi()
.AddComposers()
.Build();

builder.Services.AddScoped(provider =>
{
var applicationManager = provider.GetRequiredService();
return new CustomApplicationManager(applicationManager);
});
builder.Services.AddHttpClient();
builder.Services.AddSession();

builder.Services.AddTransient();

builder.Services.AddCors(options =>
{
options.AddPolicy(“AllowAllOrigins”,
policy =>
{
policy.AllowAnyOrigin() // Allows requests from any origin
.AllowAnyHeader() // Allows any header
.AllowAnyMethod(); // Allows any HTTP method (GET, POST, etc.)
});
});

WebApplication app = builder.Build();

await app.BootUmbracoAsync();

app.UseSession();
app.UseCors(“AllowAllOrigins”);

app.UseUmbraco()
.WithMiddleware(u =>
{
u.UseBackOffice();
u.UseWebsite();
})
.WithEndpoints(u =>
{
u.UseBackOfficeEndpoints();
u.UseWebsiteEndpoints();
});

app.MapPost(“/create-client”, async (ClientModel model, CustomApplicationManager applicationManager) =>
{
try
{
if (string.IsNullOrEmpty(model.ClientId))
return Results.BadRequest(“Client ID is required.”);

if (!Uri.TryCreate(model.RedirectUri, UriKind.Absolute, out var redirectUri))
return Results.BadRequest(“Invalid redirect URI.”);

await applicationManager.EnsureCustomApplicationAsync(model.ClientId, redirectUri);
return Results.Ok(“Client created/updated successfully.”);
}
catch (Exception ex)
{
return Results.Problem(ex.Message);
}
}).WithName(“CreateClient”);

app.MapGet(“/login”, (Auth auth, IConfiguration config, IBackOfficeApplicationManager backOfficeApplicationManager) =>
{
var baseUrl = config[“Umbraco:BaseUrl”];
var authorizationUrl = auth.GetAuthorizationUrl();
return Results.Redirect(baseUrl + authorizationUrl);
});

app.MapGet(“/callback”, async (Auth auth, HttpContext httpContext, IConfiguration configuration) =>
{
var code = httpContext.Request.Query[“code”];
var state = httpContext.Request.Query[“state”];
if (string.IsNullOrEmpty(code) || string.IsNullOrEmpty(state))
{
return Results.BadRequest(“Invalid callback parameters”);
}
try
{
var tokenResponse = await auth.HandleCallback(code, state);
// Store the token securely
httpContext.Response.Cookies.Append(“UmbracoToken”, tokenResponse, new CookieOptions
{
HttpOnly = true,
Secure = true,
SameSite = SameSiteMode.Strict
});
return Results.Redirect(“/dashboard”);
}
catch (Exception ex)
{
return Results.BadRequest($”Authentication failed: {ex.Message}”);
}
});

await app.RunAsync();

public class ClientModel
{
public string ClientId { get; set; }
public string RedirectUri { get; set; }
//public string ClientSecret { get; set; } // only use if it’s a confidential app
}

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

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

و در اینجا پیاده سازی برای CustomApplicationManager کلاس:منبع: (https://github.com/umbraco/Umbraco-CMS/blob/contrib/src/Umbraco.Cms.Api.Management/Security/BackOfficeApplicationManager.cs)

using OpenIddict.Abstractions;
using Umbraco.Cms.Infrastructure.Security;

namespace UmbDemo14.Web
{
public class CustomApplicationManager : OpenIdDictApplicationManagerBase
{
public CustomApplicationManager(IOpenIddictApplicationManager applicationManager)
: base(applicationManager)
{
}

public async Task EnsureCustomApplicationAsync(string clientId, Uri redirectUri, CancellationToken cancellationToken = default)
{
if (redirectUri.IsAbsoluteUri == false)
{
throw new ArgumentException(“The provided URL must be an absolute URL.”, nameof(redirectUri));
}

var clientDescriptor = new OpenIddictApplicationDescriptor
{
DisplayName = “Custom Application”,
ClientId = clientId,
RedirectUris = { redirectUri },
ClientType = OpenIddictConstants.ClientTypes.Public, // change to confidential for client secret
Permissions = {
OpenIddictConstants.Permissions.Endpoints.Authorization,
OpenIddictConstants.Permissions.Endpoints.Token,
OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode,
OpenIddictConstants.Permissions.ResponseTypes.Code
}
};

await CreateOrUpdate(clientDescriptor, cancellationToken);
}
public async Task DeleteCustomClientApplicationAsync(string clientId, CancellationToken cancellationToken)
{
await Delete(clientId, cancellationToken);
}
}
}

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

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

حرکت رو به جلو: چگونه می توانیم پیشرفت کنیم

Umbraco's Management API یک ابزار قدرتمند است، اما مانند هر ابزاری، پتانسیل کامل آن تنها در صورتی قابل تحقق است که کاربران بتوانند نحوه استفاده موثر از آن را درک کنند. مایلم Umbraco اسناد خود را گسترش دهد تا راهنماهای عملی تر و گام به گام برای راه اندازی مدیریت API در محیط های محلی و تولیدی را شامل شود. این باید شامل موارد زیر باشد:

مراحل تفصیلی برای مجوز تولید: پوشش راه‌اندازی OAuth2، بهترین روش‌ها برای امنیت، و استفاده از “آفیس پشتیبان umbraco” در یک سناریوی تولید بدون Swagger.
نکات محیطی محلی: ارائه دستورالعمل های صریح تر در مورد نحوه ترجمه مجوزهای Swagger/Postman به یک تنظیم محلی. این به کاهش سردرگمی برای توسعه دهندگانی که در یک گردش کار ترکیبی کار می کنند کمک می کند.

با پرداختن به این حوزه ها، Umbraco می تواند تجربه توسعه دهندگان را به طور قابل توجهی افزایش دهد و در نهایت پذیرش، گسترش و نوآوری با مدیریت API را برای جامعه آسان تر کند.

نتیجه گیری

وضعیت فعلی مدیریت API یک پایه محکم است، اما مجوز همچنان حوزه ای است که در آن جا برای بهبود وجود دارد. توسعه دهندگانی که با محیط های محلی و تولیدی کار می کنند به چیزی بیش از نمونه های Swagger یا Postman نیاز دارند. آنها به یک راهنمای کامل برای راه اندازی ادغام های ایمن و انعطاف پذیر نیاز دارند. من امیدوارم که با ادامه بازخورد و مشارکت‌های جامعه، اسناد Umbraco برای پوشش این شکاف‌ها رشد کند و مدیریت API را برای همه قابل دسترس‌تر کند.

{
  "BaseUrl": "https://localhost:44329",
  "ClientId": "newclientId", // generated through /create-client
  "AuthorizationEndpoint": "/umbraco/management/api/v1/security/back-office/authorize",
  "TokenEndpoint": "/umbraco/management/api/v1/security/back-office/token",
  "RedirectUri": "https://localhost:44329/callback"
}

using Microsoft.AspNetCore.Mvc;
using OpenIddict.Abstractions;
using OpenIddict.Core;
using UmbDemo14.Web;
using Microsoft.Extensions.Options;
using Umbraco.Cms.Api.Management.Security;
using Umbraco.Cms.Infrastructure.Security;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .Build();

builder.Services.AddScoped(provider =>
{
    var applicationManager = provider.GetRequiredService();
    return new CustomApplicationManager(applicationManager);
});
builder.Services.AddHttpClient();
builder.Services.AddSession();

builder.Services.AddTransient();

builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAllOrigins",
        policy =>
        {
            policy.AllowAnyOrigin()   // Allows requests from any origin
                  .AllowAnyHeader()   // Allows any header
                  .AllowAnyMethod();  // Allows any HTTP method (GET, POST, etc.)
        });
});

WebApplication app = builder.Build();

await app.BootUmbracoAsync();

app.UseSession();
app.UseCors("AllowAllOrigins");

app.UseUmbraco()
    .WithMiddleware(u =>
    {
        u.UseBackOffice();
        u.UseWebsite();
    })
    .WithEndpoints(u =>
    {
        u.UseBackOfficeEndpoints();
        u.UseWebsiteEndpoints();
    });

app.MapPost("/create-client", async (ClientModel model, CustomApplicationManager applicationManager) =>
{
    try
    {
        if (string.IsNullOrEmpty(model.ClientId))
            return Results.BadRequest("Client ID is required.");

        if (!Uri.TryCreate(model.RedirectUri, UriKind.Absolute, out var redirectUri))
            return Results.BadRequest("Invalid redirect URI.");

        await applicationManager.EnsureCustomApplicationAsync(model.ClientId, redirectUri);
        return Results.Ok("Client created/updated successfully.");
    }
    catch (Exception ex)
    {
        return Results.Problem(ex.Message);
    }
}).WithName("CreateClient");

app.MapGet("/login", (Auth auth, IConfiguration config, IBackOfficeApplicationManager backOfficeApplicationManager) =>
{
    var baseUrl = config["Umbraco:BaseUrl"];
    var authorizationUrl = auth.GetAuthorizationUrl();
    return Results.Redirect(baseUrl + authorizationUrl);
});

app.MapGet("/callback", async (Auth auth, HttpContext httpContext, IConfiguration configuration) =>
{
    var code = httpContext.Request.Query["code"];
    var state = httpContext.Request.Query["state"];
    if (string.IsNullOrEmpty(code) || string.IsNullOrEmpty(state))
    {
        return Results.BadRequest("Invalid callback parameters");
    }
    try
    {
        var tokenResponse = await auth.HandleCallback(code, state);
        // Store the token securely
        httpContext.Response.Cookies.Append("UmbracoToken", tokenResponse, new CookieOptions
        {
            HttpOnly = true,
            Secure = true,
            SameSite = SameSiteMode.Strict
        });
        return Results.Redirect("/dashboard");
    }
    catch (Exception ex)
    {
        return Results.BadRequest($"Authentication failed: {ex.Message}");
    }
});

await app.RunAsync();

public class ClientModel
{
    public string ClientId { get; set; }
    public string RedirectUri { get; set; }
    //public string ClientSecret { get; set; } // only use if it's a confidential app
}

using OpenIddict.Abstractions;
using Umbraco.Cms.Infrastructure.Security;

namespace UmbDemo14.Web
{
    public class CustomApplicationManager : OpenIdDictApplicationManagerBase
    {
        public CustomApplicationManager(IOpenIddictApplicationManager applicationManager)
            : base(applicationManager)
        {
        }

        public async Task EnsureCustomApplicationAsync(string clientId, Uri redirectUri, CancellationToken cancellationToken = default)
        {
            if (redirectUri.IsAbsoluteUri == false)
            {
                throw new ArgumentException("The provided URL must be an absolute URL.", nameof(redirectUri));
            }

            var clientDescriptor = new OpenIddictApplicationDescriptor
            {
                DisplayName = "Custom Application",
                ClientId = clientId,
                RedirectUris = { redirectUri },
                ClientType = OpenIddictConstants.ClientTypes.Public, // change to confidential for client secret
                Permissions = {
                    OpenIddictConstants.Permissions.Endpoints.Authorization,
                    OpenIddictConstants.Permissions.Endpoints.Token,
                    OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode,
                    OpenIddictConstants.Permissions.ResponseTypes.Code
                }
            };

            await CreateOrUpdate(clientDescriptor, cancellationToken);
        }
        public async Task DeleteCustomClientApplicationAsync(string clientId, CancellationToken cancellationToken)
        {
            await Delete(clientId, cancellationToken);
        }
    }
}