Harici Kimlik Sağlayıcılar

Kullanıcılar Google, Apple, Facebook ya da Microsoft'ta zaten sahip oldukları bir hesapla giriş yapabilir. İstemci uygulamanız sağlayıcının kendi giriş akışını (SDK'sını ya da web akışını) çalıştırır ve sonucu ErtisAuth'a gönderir; ErtisAuth sonucu sağlayıcıya doğrulatır ve tıpkı şifreyle girişte olduğu gibi bir ErtisAuth token çifti döner.

Uygulama ──(1) sağlayıcı girişi──▶ Google / Apple / Facebook / Microsoft
    │                                          │
    │◀──────────(2) sağlayıcı token'ı ─────────┘
    │
    └──(3) POST /oauth/{slug}/login ──▶ ErtisAuth ──(4) doğrula─▶ sağlayıcı
                                           │
    ◀──────────(5) ErtisAuth token'ları ───┘

İlk girişte kullanıcı oluşturulur; sonraki girişler aynı kullanıcıyı yeniden bulur.

Desteklenen sağlayıcılar#

Kimlik (sağlayıcıdaki kullanıcı id'si, e-posta adresi) her zaman ErtisAuth'un sağlayıcıdan aldığı veriden alınır; istemcinin iddia ettiğinden asla alınmaz. İstemcinin gönderdiği adlar yalnızca sağlayıcının bunları yalnızca istemciyle paylaştığı durumlarda kullanılır (Apple kullanıcının adını yalnızca bir kez, uygulamaya gönderir).

Sağlayıcı nesnesi#

{
	"_id": "66f1c0d2a4b5c6d7e8f90180",
	"type": "Google",
	"name": "Google",
	"slug": "google",
	"description": "Sign in with Google for the web app",
	"defaultRole": "customer",
	"defaultUserType": "customer",
	"appClientId": "1234567890-abc.apps.googleusercontent.com",
	"isActive": true,
	"trust_email": false,
	"membership_id": "66f1c0d2a4b5c6d7e8f90123"
}

Aynı tipte birden fazla sağlayıcı oluşturabilirsiniz; örneğin her uygulama için kendi client id'si ve kendi slug'ı olan bir Google sağlayıcısı.

Varsayılan kullanıcı tipi, sağlayıcının doldurduğu alanlara (firstname, lastname, email_address, username) izin vermelidir. Kullanıcı tipi avatar adında bir object alanı tanımlıyorsa sağlayıcının profil resmi URL'si avatar.url alanında saklanır.

Giriş yapma#

POST /oauth/{slug}/login
X-Ertis-Alias: <membership_id>
Content-Type: application/json

Token gerekmez. Gövde, sağlayıcının tipine göre değişir.

Google#

{
	"clientId": "1234567890-abc.apps.googleusercontent.com",
	"token": {
		"idToken": "eyJhbGciOiJSUzI1NiIs…"
	}
}

ID token, sağlayıcının appClientId değeri için üretilmiş olmalı ve kullanıcının e-postasını ve adını içermelidir: openid email profile scope'larını isteyin. Bunları içermeyen bir token 401 ProviderProfileIncomplete döner.

Facebook#

{
	"appId": "<facebook_app_id>",
	"user": {
		"id": "<facebook_user_id>",
		"first_name": "Ada",
		"last_name": "Lovelace",
		"email": "ada@example.com",
		"accessToken": "<facebook_access_token>"
	}
}

appId, sağlayıcının appClientId değeri olmalıdır. Gövdede id, first_name, email ve accessToken zorunludur; ama ErtisAuth'un kullandığı kimlik ve e-posta adresi access token ile Facebook'tan okunur. Facebook Limited Login (iOS) için URL'ye ?limited_flow=true ekleyin ve Limited Login authentication token'ını accessToken olarak gönderin.

Microsoft#

{
	"clientId": "<application_client_id>",
	"token": {
		"accessToken": "<access_token_for_microsoft_graph>"
	}
}

Access token, Microsoft Graph için geçerli olmalıdır (User.Read).

Apple ve AppleNative#

{
	"authorization": {
		"code": "<authorization_code>",
		"id_token": "<id_token>"
	},
	"user": {
		"name": { "firstName": "Ada", "lastName": "Lovelace" },
		"email": "ada@example.com"
	}
}

Bu, Sign in with Apple'ın olduğu gibi gönderilen yanıtıdır. user yalnızca kullanıcının ilk girişinde, Apple adı uygulamayla paylaştığında bulunur; elinizdeyse gönderin. ErtisAuth code değerini Apple ile değiştirir; bu yüzden bir kod yalnızca bir kez kullanılabilir ve birkaç dakika içinde süresi dolar.

Yanıt#

Şifreyle girişte olduğu gibi bir ErtisAuth token çiftiyle 201 Created.

Hatalar#

Kullanıcılar nasıl eşleştirilir#

1. Bağlı hesapla. Her kullanıcı giriş yaptığı hesapları connected_accounts alanında tutar:
   json

   "connected_accounts": [
   	{ "provider": "Google", "slug": "google", "user_id": "109876543210987654321" }
   ]

   Bir giriş, bağlı hesabı aynı sağlayıcı tipine ve aynı sağlayıcı kullanıcı id'sine sahip kullanıcıyı bulur.
2. E-posta adresiyle. Hiçbir bağlı hesap eşleşmezse ErtisAuth membership içinde aynı e-posta adresine sahip bir kullanıcı arar ve sağlayıcı hesabını ona bağlar; aşağıya bakın.
3. Kayıt. Hiçbir kullanıcı eşleşmezse sağlayıcının defaultRole ve defaultUserType değerleriyle, sağlayıcıdan gelen ad ve e-postayla, username olarak e-posta adresiyle ve source_provider alanı sağlayıcının tipi olacak şekilde yeni bir kullanıcı oluşturulur. Bu kullanıcının şifresi yoktur ve sağlayıcı üzerinden giriş yapar.

Her giriş bir TokenGenerated olayı kaydeder; kayıt ayrıca UserCreated kaydeder.

Mevcut hesaplara bağlama#

Bir sağlayıcı hesabını e-posta adresiyle mevcut bir kullanıcıya bağlamak, ancak sağlayıcı kullanıcının o adrese sahip olduğunu garanti ediyorsa güvenlidir. Aksi halde herkes başka birinin e-posta adresiyle bir sağlayıcı hesabı açıp onun ErtisAuth hesabını ele geçirebilirdi.

Aynı e-posta adresine sahip mevcut bir kullanıcı varsa ve e-postaya güvenilemiyorsa giriş 409 ProviderEmailNotTrusted ile reddedilir. Kullanıcı şifresiyle giriş yapabilir; ardından hesabı bağlamasına izin verebilirsiniz.

Hesap aktivasyonu#

Membership aktivasyon istiyorsa, sağlayıcıyla kayıt olan kullanıcılar da diğer kullanıcılar gibi aktif olmadan oluşturulur ve hook kuruluysa aktivasyon e-postasını alır.

Çıkış yapma#

Bir ErtisAuth token'ını iptal etmek, sağlayıcı destekliyorsa kullanıcının bağlı hesabıyla birlikte saklanan sağlayıcı token'ını da iptal eder.

Sağlayıcıları yönetme#

Tüm route'lar /memberships/{membershipId} altındadır.

Aktif sağlayıcılar#

GET /memberships/{membershipId}/providers/active-providers herkese açıktır; böylece giriş sayfaları doğru butonları gösterebilir. Yalnızca herkese açık ayarları döner:

[
	{ "_id": "…", "name": "Google", "slug": "google", "type": "Google", "appClientId": "1234567890-abc.apps.googleusercontent.com", "membership_id": "…" },
	{ "_id": "…", "name": "Apple", "slug": "apple", "type": "Apple", "appClientId": "com.example.web", "redirectUri": "https://app.example.com/auth/apple", "membership_id": "…" },
	{ "_id": "…", "name": "Microsoft", "slug": "microsoft", "type": "Microsoft", "appClientId": "…", "tenantId": "…", "membership_id": "…" }
]

Sağlayıcı oluşturma#

curl -X POST https://auth.example.com/memberships/<membership_id>/providers \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"type": "Apple",
		"name": "Sign in with Apple",
		"slug": "apple",
		"defaultRole": "customer",
		"defaultUserType": "customer",
		"appClientId": "com.example.web",
		"teamId": "ABCDE12345",
		"privateKeyId": "XYZ987WVU6",
		"privateKey": "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMG…\n-----END PRIVATE KEY-----",
		"redirectUri": "https://app.example.com/auth/apple",
		"isActive": true
	}'

Yanıt 201 Created: sağlayıcı.

Sağlayıcı güncelleme#

PUT /memberships/{membershipId}/providers/{id}

Gönderilmeyen alanlar mevcut değerlerini korur. type değişemez; farklı bir slug 400 ProviderSlugCannotBeChanged döner. Hiçbir değişiklik içermeyen bir güncelleme 409 IdenticalDocumentError döner.

Sağlayıcı silme#

DELETE /memberships/{membershipId}/providers/{id}

Yanıt 204 No Content. Sağlayıcının oluşturduğu kullanıcılar hesaplarını korur.

Olaylar#

ProviderCreated, ProviderUpdated ve ProviderDeleted. Bkz. Olaylar.