MMX Permissions — Kurulum ve Kullanım Kılavuzu

Bu kılavuz, MMX Permissions kütüphanesinin ne yaptığını, nasıl yapılandırıldığını ve yönetim arayüzünün nasıl kullanıldığını açıklar.

İçindekiler

MMX Permissions — Kurulum ve Kullanım Kılavuzu

1. Genel Bakış

MMX Permissions, ASP.NET Core tabanlı uygulamalara granüler izin yönetimi ekleyen bir kütüphanedir. Temel amacı şudur:

Sistemdeki API endpoint'lerini tanımlamak ve bunlara izin kodu atamak
Kullanıcıların sahip olduğu rollere göre bu izinlere erişimlerini otomatik olarak denetlemek
Tüm bu yapılandırmayı bir web arayüzü üzerinden kolayca yönetmek

Kütüphane iki ana bileşenden oluşur:

Bileşen	Açıklama
mmx-permissions.Core	İzin denetim motoru, veritabanı, API endpoint'leri ve middleware
mmx-permissions.UI	Tarayıcı üzerinden izin yönetimi yapılabilen Razor Class Library

2. Temel Kavramlar

İzin (Permission)

Sistemde tanımlanmış bir yetkiyi temsil eden isimlendirilmiş bir nesnedir. Her iznin benzersiz bir kodu ve açıklaması vardır.

Örnek izinler:

users.read — Kullanıcıları listeleme yetkisi
product.edit — Ürün düzenleme yetkisi
order.delete — Sipariş silme yetkisi

Rol (Security Role)

Roller dışarıdan gelir; MMX Permissions kendi rol veritabanını tutmaz. Roller, uygulamanın bağlı olduğu kimlik sağlayıcısından (Identity Server, Azure AD, vb.) okunur. Bir role bir veya birden fazla izin atanabilir. Kullanıcı hangi rolü taşıyorsa, o rolün tüm izinlerine otomatik olarak sahip olur.

Endpoint

Uygulamada bulunan bir HTTP yolunun (controller + action veya endpoint grubu) temsilidir. Her endpoint'e hangi izinlerin erişebileceği tanımlanır.

Endpoint Grubu (Endpoint Group)

Birden fazla endpoint'i mantıksal olarak bir araya getiren bir etiket. Örneğin "Products" grubu altında ürünlerle ilgili tüm endpoint'ler toplanabilir. Grup bazlı izin tanımlaması, tek tek endpoint tanımlamaktan daha pratiktir.

İzin Denetimi Akışı (Özet)

Kullanıcı → JWT Token → Middleware → Kullanıcının rolleri → Rollerin izinleri → Endpoint izni → ✅ veya ❌

3. Mimari: Sistem Nasıl Çalışır?

MMX Permissions, bir HTTP isteği geldiğinde devreye giren bir middleware (ara katman yazılımı) içerir. Bu middleware şu adımları sırasıyla gerçekleştirir:

1. Yolu Filtrele Statik dosyalar (CSS, JS, resimler), temel sistem endpoint'leri ve kimlik doğrulama yolları denetim dışında tutulur.

2. Kullanıcı Kimliğini Doğrula JWT token'dan kullanıcı kimliği okunur. Token geçerli değilse istek reddedilir (401 Unauthorized).

3. Endpoint'i Tanımla Middleware, gelen isteğin hangi controller/action veya endpoint grubuna ait olduğunu otomatik olarak tespit eder. Bunu yapmak için birden fazla strateji kullanır:

ASP.NET Core route verisi
Endpoint metadata analizi
Sınıf adı örüntüsü tanıma

4. Kullanıcı İzinlerini Kontrol Et Harici rol servisi aracılığıyla kullanıcının rollerine bakılır. Bu rollere atanmış izinler toplanır. Endpoint için gereken izinlerle karşılaştırılır.

5. Karar Ver

Kullanıcı gerekli izne sahipse: istek geçer ✅
Sahip değilse: 403 Forbidden döner ❌
Endpoint'e hiç izin tanımlanmamışsa: AllowUnprotectedEndpoints ayarına göre karar verilir

Not: Roller her zaman dışarıdan gelir. MMX Permissions, kullanıcıların hangi rollere sahip olduğunu kendi veritabanında saklamaz; bu bilgiyi IRoleService arayüzü üzerinden alır. Bu arayüzü uygulamanın kendi kimlik sistemiyle entegre etmek geliştiricinin sorumluluğundadır.

4. Ön Koşullar

MMX Permissions'ı kullanabilmek için aşağıdakiler gereklidir:

Gereksinim	Detay
.NET	.NET 8 veya üzeri
Veritabanı	Microsoft SQL Server veya PostgreSQL
Kimlik Sağlayıcı	OpenID Connect destekleyen herhangi bir sunucu (IdentityServer, Azure AD, Keycloak, vb.)
JWT Token	Kullanıcıların `admin` rol talebini (claim) taşıyan geçerli bir JWT token'ı olmalıdır

Yönetim arayüzüne yalnızca admin rolüne sahip kullanıcılar erişebilir. Bu rol kimlik sağlayıcınızda tanımlanmış ve kullanıcılara atanmış olmalıdır.

5. Konfigürasyon

Tüm ayarlar appsettings.json dosyası üzerinden yapılır.

5.1 Veritabanı Bağlantısı

SQL Server için

{
  "MmxPermissions": {
    "Core": {
      "ConnectionString": "Server=sunucu_adresi;Database=MmxPermissions;User Id=kullanici;Password=sifre;TrustServerCertificate=true;",
      "DatabaseProvider": "SqlServer"
    }
  }
}

PostgreSQL için

{
  "MmxPermissions": {
    "Core": {
      "ConnectionString": "Host=sunucu_adresi;Database=mmx_permissions;Username=kullanici;Password=sifre;",
      "DatabaseProvider": "PostgreSQL"
    }
  }
}

Bağlantı dizesindeki sunucu_adresi, kullanici ve sifre değerlerini kendi ortamınıza göre güncelleyin. Üretim ortamında bağlantı dizesini düz metin yerine ortam değişkenleri veya bir secret yöneticisi (Azure Key Vault, AWS Secrets Manager vb.) aracılığıyla sağlamanız önerilir.

5.2 Çekirdek Ayarlar

{
  "MmxPermissions": {
    "Core": {
      "ConnectionString": "...",
      "DatabaseProvider": "SqlServer",
      "EnablePermissionMiddleware": true,
      "AllowUnprotectedEndpoints": true,
      "DevelopmentStartupDelayMs": 5000
    }
  }
}

Parametre	Tür	Varsayılan	Açıklama
`ConnectionString`	`string`	—	Veritabanı bağlantı dizesi (zorunlu)
`DatabaseProvider`	`string`	`"SqlServer"`	Veritabanı türü: `"SqlServer"` veya `"PostgreSQL"`
`EnablePermissionMiddleware`	`bool`	`true`	İzin denetim middleware'ini aktif eder/pasifleştirir
`AllowUnprotectedEndpoints`	`bool`	`true`	`true`: İzin tanımlanmamış endpoint'lere herkes erişebilir. `false`: İzin tanımlanmamış endpoint'ler varsayılan olarak engellenir
`DevelopmentStartupDelayMs`	`int`	`5000`	Geliştirme ortamında başlangıç gecikmesi (ms). Veritabanının hazır olmasını beklemek için kullanılır

AllowUnprotectedEndpoints için önerilen yaklaşım:

Ortam	Önerilen Değer	Sebep
Geliştirme / Test	`true`	Henüz izin tanımlanmamış endpoint'leri test edebilmek için
Üretim	`false`	Güvenlik: tüm endpoint'lerin açıkça yetkilendirilmesi zorunlu olsun

5.3 Kimlik Doğrulama (OpenID Connect) Ayarları

Yönetim arayüzü, kullanıcıları kimlik sağlayıcınıza yönlendirerek oturum açtırır.

{
  "MmxPermissions": {
    "UI": {
      "Authority": "https://kimlik-sunucunuz.com",
      "ClientId": "mmx-permissions-client",
      "ClientSecret": "gizli-anahtar",
      "Scopes": ["openid", "profile", "roles"],
      "SessionTimeoutMinutes": 30,
      "NameClaimType": "name",
      "RoleClaimType": "role"
    }
  }
}

Parametre	Açıklama
`Authority`	OpenID Connect kimlik sağlayıcısının URL'i
`ClientId`	Kimlik sağlayıcıda kayıtlı uygulama kimliği
`ClientSecret`	Uygulama gizli anahtarı (üretimde secret yöneticisinde tutulmalıdır)
`Scopes`	İstenen OAuth kapsamları. `roles` kapsamı, rol bilgisinin token'a dahil edilmesi için gereklidir
`SessionTimeoutMinutes`	Oturum zaman aşımı (dakika). Varsayılan: `30`
`NameClaimType`	Kullanıcı adı için kullanılacak claim türü
`RoleClaimType`	Rol bilgisi için kullanılacak claim türü. Kimlik sağlayıcınızın gönderdiği claim adıyla eşleşmelidir

Önemli: Kimlik sağlayıcınızda admin adında bir rol tanımlanmış olmalı ve yönetici kullanıcıların bu rol ile oturum açması gerekir. RoleClaimType değeri, token içindeki rol alanının adıyla birebir eşleşmelidir.

6. Yönetim Arayüzü

Yönetim arayüzüne aşağıdaki adres üzerinden erişilir (alan adı ve port uygulamanıza göre değişir):

https://uygulamaniz.com/mmxpermissions

Oturum açmak için kimlik sağlayıcınıza yönlendirilirsiniz. Yalnızca admin rolüne sahip kullanıcılar giriş yapabilir.

6.1 Ana Sayfa (Dashboard)

Giriş yaptıktan sonra karşınıza aşağıdaki yönetim kartları çıkar:

Kart	Açıklama
Users	Kullanıcıları ve rollerini görüntüler
Roles	Rolleri ve bu rollere atanmış izinleri yönetir
Permissions	Sistemdeki izinleri (permission) oluşturur, düzenler, siler
Endpoints	Tek tek endpoint izinlerini yapılandırır
Endpoint Groups	Gruplandırılmış endpoint izinlerini yapılandırır (yakında — henüz aktif değil)

6.2 İzinler (Permissions)

Bu ekranda sistemde tanımlı tüm izinleri görebilir ve yönetebilirsiniz.

Yeni izin oluşturma:

Permissions kartına tıklayın.
Create / Yeni İzin butonuna tıklayın.
Aşağıdaki alanları doldurun:

Alan Açıklama Örnek
Code İznin benzersiz kod adı users.read
Description İznin ne işe yaradığını açıklayan metin Kullanıcı listesini görüntüleme yetkisi
Kaydedin.

Alan	Açıklama	Örnek
Code	İznin benzersiz kod adı	`users.read`
Description	İznin ne işe yaradığını açıklayan metin	`Kullanıcı listesini görüntüleme yetkisi`

İzin güncelleme: Listeden ilgili izne tıklayın ve alanları düzenleyin.

İzin silme: Silmek istediğiniz iznin yanındaki sil butonuna tıklayın. Bu işlem geri alınamaz; silinen iznin tüm endpoint ve rol ilişkileri de kaldırılır.

6.3 Roller (Roles)

Roller harici kimlik sisteminizden okunur; bu ekranda yeni rol oluşturamazsınız. Ancak mevcut rollere izin atayabilir veya atanmış izinleri kaldırabilirsiniz.

Bir role izin atama:

Roles kartına tıklayın.
İzin atamak istediğiniz rolü seçin.
Assign Permission / İzin Ata seçeneğine tıklayın.
Listeden atamak istediğiniz izni seçin ve onaylayın.

Rol izinlerini görüntüleme:

Bir rolün üzerine tıkladığınızda o role atanmış tüm izinleri görebilirsiniz.

Bir rolden izin kaldırma:

Rol detayında ilgili iznin yanındaki kaldır butonuna tıklayın.

6.4 Kullanıcılar (Users)

Bu ekranda sisteme erişen kullanıcılar ve sahip oldukları roller listelenir.

Kullanıcı listesi harici kimlik sisteminizden gelir; burada kullanıcı oluşturma veya silme işlemi yapılmaz.
Bir kullanıcıya tıklayarak hangi rollere sahip olduğunu ve dolayısıyla hangi izinlere erişebildiğini görebilirsiniz.

6.5 Endpoint'ler

Bu ekranda uygulamada keşfedilmiş API endpoint'leri listelenir ve her bir endpoint için hangi izinlerin gerektiği tanımlanabilir.

Endpoint'e izin atama:

Endpoints kartına tıklayın.
İzin tanımlamak istediğiniz endpoint'i bulun (controller ve action adına göre filtreleyebilirsiniz).
Assign Permissions / İzin Ata seçeneğine tıklayın.
Listeden bir veya birden fazla izin seçin ve onaylayın.

Endpoint izni kaldırma:

Endpoint detayında ilgili iznin yanındaki kaldır butonuna tıklayın.

İpucu: Eğer aynı izin kümesine sahip çok sayıda endpoint varsa, bu endpoint'leri bir Endpoint Grubuna dahil etmek ve gruba izin tanımlamak daha pratik olacaktır. Bu özellik şu an geliştirme aşamasındadır ve ilerleyen sürümlerde kullanıma açılacaktır.

6.6 Endpoint Grupları

⚠️ Bu özellik henüz aktif değildir. Endpoint Grupları özelliği gelecek sürümlerde geliştirilecek ve kullanıma açılacaktır. Aşağıdaki bilgiler planlanan işlevselliği tanıtmak amacıyla verilmiştir.

Endpoint grupları, birden fazla endpoint'i mantıksal olarak bir araya getirmenizi sağlayacaktır. Bir gruba atanan izin, o gruba dahil tüm endpoint'ler için geçerli olacaktır.

Grup bazlı izin tanımlamanın avantajı (planlanan):

Products grubuna products.manage iznini bir kez tanımlamak yeterli olacaktır; grup altındaki tüm endpoint'ler bu izni miras alacaktır.
Yeni bir endpoint eklendiğinde, sadece gruba dahil etmek yeterli olacak; tek tek izin ataması gerekmeyecektir.

7. İzin Denetimi: Akış Şeması

Bir kullanıcının herhangi bir endpoint'e erişmeye çalıştığında sistemin nasıl karar verdiğini gösteren akış:

8. Önbellekleme (Caching)

MMX Permissions, veritabanı sorgularını minimize etmek için bir önbellekleme katmanı kullanır. Bu sayede her HTTP isteğinde veritabanına gidilmez.

Önbelleklenen Veriler ve Süreleri

Veri	Önbellek Anahtarı	Süre
Kullanıcı izin kodları	`user_permission_codes:{userId}`	30 dakika
Kullanıcı rolleri	`user_roles:{userId}`	15 dakika
Endpoint izinleri	`endpoint_permissions:{controller}:{action}`	1 saat
Endpoint grup izinleri	`endpoint_group_permissions:{group}`	1 saat

Önbelleği Geçersiz Kılma

Aşağıdaki durumlarda ilgili önbellek verisi otomatik olarak süresi dolduğunda yenilenir. Değişikliklerin anında yansımasını istiyorsanız uygulamayı yeniden başlatmak gerekebilir veya geliştirici ekibiniz özel invalidation mekanizması kurmuş olabilir:

Bir role yeni izin eklendiğinde veya izin kaldırıldığında
Bir endpoint'in izin tanımları değiştiğinde
Kullanıcının rol atamaları değiştiğinde

9. Güvenlik

MMX Permissions, çok katmanlı bir güvenlik modeli uygular:

Kimlik Doğrulama

Tüm yönetim sayfaları ve API endpoint'leri için geçerli bir JWT Bearer token zorunludur.
Yönetim arayüzü ek olarak OpenID Connect ile kimlik doğrulaması yapar.

Yetkilendirme (Çok Katmanlı)

Katman	Kontrol
UI Katmanı	Razor Pages: `admin` rolü zorunludur
API Katmanı	Tüm yönetim endpoint'leri: `admin` rolü zorunludur
Middleware Katmanı	Her HTTP isteği için kullanıcı izinleri denetlenir

Öneriler

Üretim ortamında AllowUnprotectedEndpoints değerini false olarak ayarlayın.
Bağlantı dizesini ve ClientSecret değerini her zaman ortam değişkeni veya secret yöneticisi üzerinden sağlayın; kaynak koduna veya appsettings.json'a düz metin olarak yazmayın.
HTTPS kullanımı zorunludur.
admin rolünü kimlik sağlayıcınızda yalnızca güvenilir kişilere atayın.

10. Sorun Giderme

Yönetim arayüzüne erişemiyorum

Belirti	Olası Neden	Çözüm
Giriş sayfasına yönlendiriliyorum	Oturum açılmamış	Kimlik sağlayıcınız üzerinden giriş yapın
"Access Denied" sayfası görüyorum	`admin` rolünüz yok	Kimlik sağlayıcınızda kullanıcıya `admin` rolü atayın
Boş sayfa veya hata	`Authority` yanlış yapılandırılmış	`appsettings.json` içindeki `Authority` URL'ini kontrol edin
Token kabul edilmiyor	`RoleClaimType` uyuşmazlığı	Kimlik sağlayıcınızın gönderdiği rol claim adıyla `RoleClaimType` değerini eşleştirin

Kullanıcı izin gerektiren endpoint'e erişemiyor (403)

Roles ekranından kullanıcının sahip olduğu rolü kontrol edin.
İlgili rolün gerekli izne sahip olduğunu doğrulayın.
Endpoints veya Endpoint Groups ekranından endpoint'e doğru iznin atandığından emin olun.
Önbellekleme nedeniyle değişiklikler en fazla 30 dakika içinde yansır; acil durumlarda uygulamayı yeniden başlatın.

Endpoint listesinde görünmesi gereken bir endpoint yok

Uygulamanın en az bir kez çalıştırılmış ve ilgili endpoint'in route tablosuna kaydedilmiş olması gerekir.
Middleware, endpoint'leri uygulama başlangıcında otomatik olarak keşfeder; bu nedenle yeni eklenen endpoint'lerin görünmesi için uygulamanın yeniden başlatılması gerekebilir.

Veritabanına bağlanamıyor

ConnectionString değerinin doğru ve erişilebilir olduğunu kontrol edin.
DatabaseProvider değerinin veritabanı türüyle (SqlServer veya PostgreSQL) eşleştiğinden emin olun.
Geliştirme ortamında DevelopmentStartupDelayMs değerini artırarak veritabanının hazır olmasını bekleyebilirsiniz.

Bu kılavuz MMX Permissions kütüphanesinin son sürümüne aittir. Kütüphane güncellendiğinde bu belge de güncellenecektir.

İçindekiler​

1. Genel Bakış​

2. Temel Kavramlar​

İzin (Permission)​

Rol (Security Role)​

Endpoint​

Endpoint Grubu (Endpoint Group)​

İzin Denetimi Akışı (Özet)​

3. Mimari: Sistem Nasıl Çalışır?​

4. Ön Koşullar​

5. Konfigürasyon​

5.1 Veritabanı Bağlantısı​

SQL Server için​

PostgreSQL için​

5.2 Çekirdek Ayarlar​

5.3 Kimlik Doğrulama (OpenID Connect) Ayarları​

6. Yönetim Arayüzü​

6.1 Ana Sayfa (Dashboard)​

6.2 İzinler (Permissions)​

6.3 Roller (Roles)​

6.4 Kullanıcılar (Users)​

6.5 Endpoint'ler​

6.6 Endpoint Grupları​

7. İzin Denetimi: Akış Şeması​

8. Önbellekleme (Caching)​

Önbelleklenen Veriler ve Süreleri​

Önbelleği Geçersiz Kılma​

9. Güvenlik​

Kimlik Doğrulama​

Yetkilendirme (Çok Katmanlı)​

Öneriler​

10. Sorun Giderme​

Yönetim arayüzüne erişemiyorum​

Kullanıcı izin gerektiren endpoint'e erişemiyor (403)​

Endpoint listesinde görünmesi gereken bir endpoint yok​

Veritabanına bağlanamıyor​