Yetkilendirme

Çağıranın kimliği doğrulandıktan sonra ErtisAuth isteği yapıp yapamayacağına karar verir. Karar iki modeli birleştirir:

• RBAC (rol tabanlı erişim kontrolü): çağıranın rolünün yetkileri.
• UBAC (kullanıcı tabanlı erişim kontrolü): kullanıcı ya da uygulama üzerinde saklanan, çağıranın kendine ait yetkileri.

Aynı model hem ErtisAuth'un kendi API'sini hem de SDK aracılığıyla sizin API'lerinizi korur.

Yetki ifadeleri#

Bir yetki, noktalarla ayrılmış en fazla dört bölümden oluşan bir ifadedir:

subject.resource.action.object

*, bulunduğu bölümün her değeriyle eşleşir. Kısa yazımlarda eksik bölümler * sayılır:

Bölümlerin kuralları:

• resource ve action addır ve büyük/küçük harf ayrımı yapılmadan karşılaştırılır (Users.Read, users.read ile aynıdır).
• subject ve object id'dir ve birebir karşılaştırılır.
• Bir bölüm boş olamaz, . ya da * ile başlayıp bitemez ve * bir değerin parçası olarak kullanılamaz (user* geçersizdir). Geçersiz ifadeler 400 InvalidRbac ile reddedilir.

UBAC ifadeleri#

Bir kullanıcının ya da uygulamanın permissions ve forbidden listeleri aynı biçimi subject olmadan kullanır (subject, kullanıcının ya da uygulamanın kendisidir): resource.action.object; kısa yazımlar da aynıdır (users, users.read).

Bir istek nasıl kontrol edilir#

ErtisAuth, korunan bir endpoint'e gelen her istek için endpoint'ten ve çağırandan isteğin ifadesini oluşturur:

• subject: çağıranın id'si,
• resource ve action: endpoint'in tanımladığı değerler (örneğin users ve read),
• object: tek kaynak endpoint'lerinde route'taki id (GET /users/{id}), diğerlerinde *.

Örneğin 66f1…24 kullanıcısının yaptığı GET /memberships/{m}/users/66f1…27 isteği 66f1…24.users.read.66f1…27 olarak kontrol edilir.

Ardından karar bu sırayla verilir:

1. Önce UBAC. Çağıranın kendi permissions ya da forbidden listesindeki bir girdi eşleşirse kararı yalnızca çağıranın kendi girdileri verir: bir yetki eşleşir ve hiçbir yasak eşleşmezse izin verilir, aksi halde reddedilir.
2. Sonra rol. Aksi halde rol karar verir: permissions girdilerinden biri eşleşir ve forbidden girdilerinden hiçbiri eşleşmezse izin verilir. Bir yasak girdisi, aynı rolün yetkisine karşı her zaman kazanır.
3. Sonra kendi kaydı kuralları. İkisi de izin vermezse, rol işlemi açıkça yasaklamadıkça iki istisna yine de geçerlidir:
   • bir kullanıcı kendi kullanıcı kaydını, bir uygulama da kendi uygulama kaydını güncelleyebilir;
   • bir uygulama kendi uygulama kaydını okuyabilir.
4. En son scope'lar. Token bir scoped token ise, yukarıda izni hangisi vermiş olursa olsun, scope'larının da isteği kapsaması gerekir.

Reddedilen bir istek 403 AccessDenied döner.

Her kullanıcının ve uygulamanın bir rolü olmalıdır. Rolü boş olan ya da rolü artık mevcut olmayan biri, kendi yetkileri ne olursa olsun korunan her endpoint'te reddedilir (403 AccessDenied, "The user has no role" ya da "The user role is not found by the given slug"). API her zaman bir rol istediği için bu yalnızca veri API dışında değiştirildiğinde ya da hâlâ kullanımda olan bir rol silindiğinde olur.

Örnekler#

Bir rol:

{
	"name": "Support Agent",
	"slug": "support",
	"permissions": [ "users.read", "users.update", "roles.read" ],
	"forbidden": [ "users.update.66f1c0d2a4b5c6d7e8f90124" ]
}

Bu role ve kendi girdilerine sahip bir kullanıcı:

{
	"username": "agent-007",
	"role": "support",
	"permissions": [ "users.delete" ],
	"forbidden": [ "roles.read" ]
}

Aynı ifade hem permissions hem de forbidden listesinde bulunamaz: böyle bir rol ya da uygulama 400 ModelValidationError, böyle bir kullanıcı 409 UbacsConflicted ile reddedilir.

Ayrıcalıklı alanları değiştirme#

Kendi kaydı kuralı kullanıcıların kendi profillerini düzenlemesine izin verir, ama bazı alanlar güç verir. Bir kullanıcıda bunlardan herhangi birini değiştirmek, rolden ya da UBAC'tan gelen, o kullanıcı üzerinde gerçek bir users.update yetkisi gerektirir; kendi kaydı kuralı bunları kapsamaz:

• role
• permissions
• forbidden
• is_active
• user_type

Aksi halde güncelleme, alanların listesiyle birlikte 403 AccessDenied ile reddedilir.

source_provider ve connected_accounts alanlarını ErtisAuth kendisi yönetir: istemcilerin gönderdiği değerler yok sayılır.

ErtisAuth API'sinin kaynakları#

Her referans sayfası, her endpoint'in istediği yetkiyi listeler. Birkaç endpoint, beklemeyebileceğiniz bir yetki ister:

Şifre sıfırlama sayfası gibi herkese açık sayfalar bu endpoint'leri genellikle bir uygulamanın Basic token'ıyla, backend'inizden çağırır.

admin rolü#

Setup, yukarıdaki her kaynak üzerinde create, read, update ve delete yetkisine sahip ayrılmış admin rolünü oluşturur (örneğin *.users.read.*). admin slug'ına sahip başka bir rol oluşturulamaz (409 ReservedRole) ve admin rolü silinemez (409 SystemRolesCannotBeDeleted).

Yetki kontrolü#

Çağıran için#

Çağıranın token'ının, rolü, UBAC girdileri ve scope'larıyla birlikte bir şeyi yapıp yapamayacağını sorun:

GET /memberships/{membershipId}/roles/check-permission?permission=orders.approve
Authorization: Bearer <access_token>

Membership'in geçerli her token'ı bu endpoint'i çağırabilir. İzin varsa 200 OK, yoksa 401 döner.

SDK'nın, API'lerinize gelen her istekte çağırdığı endpoint budur.

Bir rol için#

GET /memberships/{membershipId}/roles/{roleId}/check-permission?permission=users.delete
Authorization: Bearer <access_token>

roles.read yetkisi gerektirir. Rolün yetkisi varsa 200 OK, yoksa 401 döner.

Kendi API'leriniz için yetki tasarlama#

Kaynaklar ve işlemler serbest adlardır; böylece kendi alanınızı modelleyebilirsiniz:

{
	"name": "Warehouse Manager",
	"slug": "warehouse-manager",
	"permissions": [
		"orders.read",
		"orders.update",
		"orders.ship",
		"products"
	],
	"forbidden": [ "products.delete" ]
}

Ardından endpoint'lerinizi aynı adlarla koruyun; bkz. .NET SDK.