Rol Parametre Yönetimi Mimarisi#

Giriş / Amaç#

Rol Parametre altyapısı, Keysis sistemi içerisinde rol tabanlı fine-grained authorization yapmayı sağlar. Bu mimari sayesinde:

• Roller ile sistemde kullanılacak parametreler eşleştirilerek tanımlanır.
• Kullanıcı profilleri, sahip oldukları rollerin parametrelerinden yalnızca belirlenen (seçilmiş) olanları alabilir.
• Geliştiriciler, backend servislerinde bu parametrelerin parameterCode değeri üzerinden hassas erişim kontrolü uygulayabilir.

Bu mekanizma sayesinde modüler, kolay yönetilebilir ve dinamik bir yetkilendirme modeli elde edilir.

Parametre Tanımı#

Fine grained access control için kullanılacak parametrelerin tanımları veritabanındaki kys_role_param_def tablosunda tutulur. Her bir parametre için bu tabloda bir kayıt bulunur ve parametreler şu alanlar ile tanımlanır:

// Parametrenin UI'de görünen adı
private String parameterName;

// Parametre açıklaması (detaylı bilgi)
private String description;

// Değer tipi (STRING, NUMBER, BOOLEAN, DATETIME veya LIST)
private Hv10AuthRoleParameterType parameterValueType;

// Parametrenin kategorisi/grubu (ör. "FINANS", "IK", "VEKALET")
private String parameterType;

// (Number tipi için) Olası minimum değer
private Integer parameterMinValue;

// (Number tipi için) Olası maksimum değer
private Integer parameterMaxValue;

// (String tipi için) Minimum uzunluk kısıtı
private Integer parameterMinLength;

// (String tipi için) Maksimum uzunluk kısıtı
private Integer parameterMaxLength;

// (Datetime tipi için) En erken tarih kısıtı
private OffsetDateTime parameterMinDate;

// (Datetime tipi için) En geç tarih kısıtı
private OffsetDateTime parameterMaxDate;

// (Boolean/List/String tipleri için) Varsayılan değer
private String parameterStringValue;

// Parametre için benzersiz kod (zorunlu alan)
private String parameterCode;

Notlar#

• parameterCode: Bu alan benzersiz olmalıdır ve geliştiriciler tüm kontrol işlemlerini bu kod üzerinden gerçekleştirir. Uygulama içinde parametreyi koşullarken bu kod kullanılır.
• parameterValueType: Parametrenin alabileceği veri tipini belirler. Bu sayede parametre değerleri için UI ve backend tarafında gerekli doğrulamalar yapılabilir (örneğin NUMBER tipindeki bir parametre için yalnızca sayısal girişe izin verilmesi gibi).
  • Geçerli tipler: STRING, NUMBER, BOOLEAN, DATETIME ve LIST.
• parameterType: Parametreleri fonksiyonel olarak gruplamak için serbest metin olarak kullanılır. Örneğin parametreler "FINANS", "IK" (İnsan Kaynakları) veya "VEKALET" gibi kategori etiketleriyle gruplanabilir.
• parameterStringValue: BOOLEAN, LIST ve STRING tipindeki parametreler için varsayılan değeri tutar (örneğin boolean tipinde varsayılan değer "false" olabilir).

Rol-Parametre Eşleştirmesi#

• Her bir rolün hangi parametrelere sahip olabileceği, kys_role_param_def_rel tablosunda tanımlanır.
• Bu tablo, rol ve parametre tanımı arasındaki çoklu-çoklu (many-to-many) ilişkiyi temsil eder. Yani bir rol birden fazla parametreyle eşleştirilebilir; aynı parametre birden fazla role atanabilir.
• Bu eşleştirmeler rol bazında hangi parametrelerin dağıtılabileceğini belirler.
• Örneğin, Yönetici rolünün "YILLIK_IZIN" ve "MASRAF_ONAY" gibi parametrelere sahip olması, ilgili role bu parametrelerin kys_role_param_def_rel tablosu üzerinden bağlanmasıyla gerçekleştirilir.

Profil-Parametre Kısıtlaması#

• Bir kullanıcı profili (son kullanıcı), sahip olduğu rollerde tanımlı tüm parametreleri otomatik olarak tamamını almak zorunda değildir. İsteğe bağlı olarak bu parametrelerin hangilerinin o kullanıcıya aktarılacağı sınırlandırılabilir.
• Bu fine grained access control, yönetim ekranındaki Profil Rol Parametre arayüzü üzerinden yapılır.
• Arayüzde, kullanıcının sahip olduğu roller listelenir ve her bir rol için istenen parametreler seçilerek o profile atanır.
• Bu kısıtlama ilişkisi veritabanında kys_profile_role_param_rel tablosunda tutulur.
• Mantık:
  • Kısıtlama yapılmadığı durumda (yani profile özgü bir seçilim yoksa) kullanıcının rolü üzerinden gelen tüm parametreler geçerli sayılır.
  • Kısıtlama yapıldığında ise sadece seçilip profile atanmış parametreler aktif olur.

Çoklu Rol Kaynağı ve Distinct ile İşlenmesi#

• Bir profilin sahip olduğu roller, sistemde birden fazla kaynaktan gelebilir.
• Kullanıcıya doğrudan atanmış rollerin yanı sıra, kullanıcı profil gruplarına dahil olabilir ve bu gruplar üzerinden roller kazanabilir.

Roller ve Parametrelerin Birleştirilmesi (Tekilleştirme)#

• Rol Kaynakları: Rol grupları tanımlanmışsa, kullanıcıya tek seferde birden fazla rol atanabilir. Kullanıcı bu rolleri doğrudan veya gruplar aracılığıyla kazanır.
• Rol Tekilleştirme (Distinct): Sistem, aktif kullanıcı için farklı kaynaklardan gelen tüm rolleri birleştirir. Aynı rolün mükerrer olması durumunda, SQL DISTINCT mantığı ile bunları tekilleştirir.
• Sonuç: Profilin tüm etkin rollerine ait rol bazında parametre bilgileri tutulmuş hale gelir.

Servis Kullanımı#

Aktif oturumdaki bir kullanıcının parametre bilgilerini almak için aşağıdaki servis uç noktası kullanılır:

GET /profile-role-parameter-values/parameter-info-by-active-profile

Bu servis, kullanıcının profil ve rol parametre ilişkilerini derleyerek iki temel kısım içeren bir yanıt döner:

• allRoleParameters: Kullanıcının sahip olduğu tüm rollerden gelen parametrelerin tamamını içerir.
• profileAssignedParameters: Profil-Parametre kısıtlama adımında profile özel atanmış parametreleri listeler. Eğer profile herhangi bir seçim yapılmadıysa bu liste boş döner ve kullanıcının rollerinin tüm parametreleri geçerli sayılır.

Whitelist / Blacklist Mantığı#

Geliştiriciler, servisten gelen veriyi kullanarak erişim kontrolünü iki farklı yaklaşımla uygulayabilir. Her iki yöntemde de kontrol mekanizması parameterCode üzerinden yürütülür.

1. Whitelist Yaklaşımı (Önerilen)#

• Sadece profileAssignedParameters listesinde bulunan parametreler dikkate alınır.
• Yani bir kullanıcının erişimine izin verilen parametreler, profile özel olarak atanmış olanlarla sınırlıdır.
• Bu yaklaşım, parametre bazlı yetkilendirmede daha sıkı kontrol sağlar ve tavsiye edilir.

2. Blacklist Yaklaşımı (Alternatif)#

• Kullanıcının tüm olası parametreleri (allRoleParameters) alınır ve profileAssignedParameters listesindeki parametreler bunlardan hariç tutularak işlem yapılır.
• Yani profile atanmış parametreler dışındakiler veya atanmışlar engelli kabul edilebilir (Yönetimi whitelist kadar kolay değildir).

İlklendirme Scriptleri#

Aşağıda, Rol Parametre yapısının veritabanı ilklendirmesine dair Liquibase formatında örnekler verilmiştir. Bu örnekler, bir senaryoya ait olmakla birlikte, geliştiricilerin kendi rolleri ve parametreleri için benzer şekilde ilklendirme yapmasına rehberlik etmesi amacıyla sunulmuştur.

1. Rol Tanımı#

Yeni bir rol tanımlamak için kys_role tablosuna kayıt atılır.

<insert tableName="kys_role">
    <column name="code" value="proxyParameterRoleCode" />
    <column name="name" value="Örnek Parametre İşlemleri" />
    <column name="editable" valueNumeric="0" />
</insert>

Açıklama: Bu örnekte yeni bir rol tanımlanmaktadır. code alanı rolün benzersiz kodunu, name alanı görünen adını temsil eder. (Diğer alanlar ortama göre uyarlanabilir.)

2. Parametre Tanımı#

Fine grained access control için kullanılacak parametre kys_role_param_def tablosuna eklenir.

<insert tableName="kys_role_param_def">
    <column name="parameter_name" value="Yıllık İzin Onay" />
    <column name="parameter_code" value="YILLIK_IZIN" />
    <column name="parameter_type" value="VEKALET" />
    <column name="parameter_value_type" value="STRING" />
    <column name="description" value="Yıllık izin onaylama yetkisi" />
</insert>

Açıklama: Burada "Yıllık İzin Onay" isimli bir parametre tanımı eklenmektedir.

• parameter_code="YILLIK_IZIN" olarak benzersiz kodu belirlenmiştir.
• parameter_type ile fonksiyonel bir grup adı verilmiş (örnekte "VEKALET").
• parameter_value_type="STRING" ile değerin metinsel tipte olacağı belirtilmiştir.
• (Gerekirse min/max veya varsayılan değer gibi diğer alanlar da eklenebilir.)

3. Rol-Parametre Eşleştirme#

Tanımlanan rol ile parametre arasındaki ilişki kys_role_param_def_rel tablosunda kurulur.

<insert tableName="kys_role_param_def_rel">
    <column name="role_id" 
            valueComputed="(SELECT id FROM kys_role WHERE code='proxyParameterRoleCode')" />
    <column name="parameter_definition_id" 
            valueComputed="(SELECT id FROM kys_role_param_def WHERE parameter_code='YILLIK_IZIN')" />
</insert>

Açıklama: Son olarak, yukarıda eklenen rol ile parametre arasında ilişki kurulmaktadır. role_id ve parameter_definition_id alanları, ilgili rolün ve parametre tanımının ID'lerini alarak bağlantıyı sağlar.

• İlişkilendirme Mantığı: Liquibase scriptlerinde role_id ve parameter_definition_id alanları, doğrudan statik ID değerleri yerine alt sorgular (sub-queries) kullanılarak doldurulur. Bu yöntem, ilgili kayıtların ID'lerini dinamik olarak çekerek veri bütünlüğünü sağlar.

Backend Kodlama Örneği#

Bir kullanıcının belirli bir parametreye sahip olup olmadığını kontrol etmek için backend tarafında parameterCode kullanılır.

Örneğin, aktif kullanıcı profiline "YILLIK_IZIN" kodlu parametre atanmışsa, yıllık izin onayı yapma yetkisi aşağıdaki mantıkla kontrol edilebilir:

boolean canApproveAnnualLeave = roleParams.contains("YILLIK_IZIN");

if (canApproveAnnualLeave) {
    // Kullanıcı yıllık izin onaylayabilir, ilgili iş kuralını çalıştır
} else {
    // Kullanıcının yetkisi yok, uygun işlemleri yap (ör. hata fırlat veya pasif et)
}

Kod Açıklaması#

• roleParams: Aktif kullanıcının sahip olduğu parametre kodlarının listesini temsil eden değişkendir.
• contains("YILLIK_IZIN"): Bu ifade, kullanıcının parametre listesinde "YILLIK_IZIN" kodunun olup olmadığını kontrol eder.
• Mantık: Sonuç true dönerse kullanıcı ilgili yetkiye sahiptir ve buna göre iş kuralı yürütülür.

Sonuç#

Bu yapı sayesinde sistem, sabit rol kontrolleri yerine dinamik parametre kodlarına dayanarak çalışır. Böylece modüler, kolay yönetilebilir ve tamamen parametrik bir yetkilendirme modeli elde edilir.