Başlangıç

Bu rehber, boş bir makineden başlayıp membership'i, yöneticisi ve ilk token'ı olan, çalışır durumda bir ErtisAuth sunucusuna ulaşmanızı sağlar. Yaklaşık on dakika sürer.

1. Gereksinimler#

• .NET 10 SDK (kaynak koddan derlemek için) ya da Docker
• MongoDB 7.0 veya üstü. Tek başına çalışan bir sunucu yeterlidir; replica set gerekmez.

2. ErtisAuth'u çalıştırın#

Kaynak koddan#

git clone https://github.com/ertugrulozcan/ErtisAuth.git
cd ErtisAuth
export Database__ConnectionString="mongodb://localhost:27017"
dotnet run --project src/ErtisAuth.WebAPI

Geliştirme ortamında API http://localhost:9716 adresinde dinler, etkileşimli API referansı da http://localhost:9716/docs adresindedir.

Docker Compose ile#

Repo, ErtisAuth'u bir MongoDB ile birlikte başlatan bir docker-compose.yml dosyası içerir:

git clone https://github.com/ertugrulozcan/ErtisAuth.git
cd ErtisAuth
docker compose up -d --build

API http://localhost:9716 adresinde dinler, API referansı http://localhost:9716/docs adresindedir. MongoDB verileri mongo-data volume'ünde saklanır.

Docker ile#

İmajı derleyin ve kendi MongoDB'nizle çalıştırın:

docker build -t ertisauth:latest .
docker run -p 9716:8080 \
	-e Database__ConnectionString="mongodb://<host>:27017" \
	ertisauth:latest

Container 8080 portunda dinler ve .NET imajlarının root olmayan app kullanıcısıyla çalışır. ICU ve saat dilimi veritabanını içeren Debian tabanlı ASP.NET Core imajını kullandığı için kültür ve saat dilimi işlemleri bir geliştirme makinesindeki gibi çalışır.

NOT: Alpine varyantı docker imajlarında lokalizasyon ve globalizasyon için ihtiyaç duyulan bazı ICU paketleri eksik olabilir. ErtisAuth için kullanımı tavsiye edilmez.

ErtisAuth verilerini Database:DefaultAuthDatabase ayarıyla belirtilen veritabanında saklar (varsayılan olarak auth). Tüm ayarlar için Yapılandırma sayfasına bakın.

ErtisAuth başlarken ihtiyaç duyduğu index'leri oluşturur. Çalıştığını kontrol edin:

curl http://localhost:9716/healthcheck

{
	"status": "Unhealthy",
	"message": "ErtisAuth has not been set up yet"
}

Bu aşamada bu mesajla birlikte Unhealthy yanıtı beklenen bir durumdur: sunucu çalışıyor, ama henüz bir membership'i yok.

3. İlk kurulumu yapın#

Yeni bir kurulumda hiç kullanıcı yoktur; bu yüzden ilk kullanıcıları oluşturmak için kimse giriş yapamaz. Setup endpoint'i bu sorunu çözer: ilk kaynakları tek bir çağrıyla oluşturur ve veritabanına sizin eklediğiniz bir token ile yetkilendirilir. Veritabanına yazma erişiminizin olması, kurulumun operatörü olduğunuzu kanıtlar.

3.1 Bir setup token'ı ekleyin#

En az 32 karakterlik rastgele bir token üretin:

openssl rand -hex 32

Token'ı ErtisAuth veritabanındaki setup koleksiyonuna ekleyin (mongosh ile):

use auth
db.setup.insertOne({ token: "<setup_token>" })

Docker Compose kullanıyorsanız komutu MongoDB container'ında çalıştırın:

docker compose exec mongo mongosh auth --eval 'db.setup.insertOne({ token: "<setup_token>" })'

3.2 Setup endpoint'ini çağırın#

curl -X POST http://localhost:9716/setup \
	-H 'X-Setup-Token: <setup_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"membership": {
			"name": "My Company",
			"slug": "my-company",
			"expires_in": 3600,
			"refresh_token_expires_in": 86400,
			"hash_algorithm": "ARGON2ID",
			"encoding": "UTF-8"
		},
		"user": {
			"username": "admin",
			"firstname": "Ada",
			"lastname": "Lovelace",
			"email_address": "admin@example.com",
			"password": "<a strong password>",
			"user_type": "Employee"
		},
		"application": {
			"name": "Backend",
			"role": "admin"
		}
	}'

Setup şunları bu sırayla oluşturur:

1. membership,
2. tüm ErtisAuth kaynakları üzerinde her yetkiye sahip admin rolü,
3. yerleşik base-user tipinden türeyen bir kullanıcı tipi,
4. admin rolüne sahip, aktif durumda yönetici kullanıcı,
5. istendiyse uygulama.

Adımlardan biri başarısız olursa ondan önce oluşturulan kaynaklar silinir; bu yüzden başarısız bir setup doğrudan tekrar denenebilir.

3.3 Yanıtı saklayın#

{
	"membership": {
		"_id": "66f1c0d2a4b5c6d7e8f90123",
		"name": "My Company",
		"slug": "my-company",
		"expires_in": 3600,
		"refresh_token_expires_in": 86400,
		"secret_key": "…",
		"hash_algorithm": "ARGON2ID",
		"encoding": "UTF-8",
		"…": "…"
	},
	"user": { "_id": "66f1c0d2a4b5c6d7e8f90124", "username": "admin", "role": "admin", "…": "…" },
	"role": { "_id": "66f1c0d2a4b5c6d7e8f90125", "name": "Administrator", "slug": "admin", "permissions": [ "*.memberships.create.*", "…" ] },
	"application": {
		"_id": "66f1c0d2a4b5c6d7e8f90126",
		"name": "Backend",
		"slug": "backend",
		"role": "admin",
		"secret": "<application_secret>"
	}
}

Şunları not edin:

• membership._id: her giriş isteğinde göndereceksiniz.
• application.secret: yalnızca bir kez döner. ErtisAuth yalnızca hash'ini saklar; kaybederseniz yenisini üretin.

Setup başarılı olunca setup koleksiyonu silinir ve endpoint kalıcı olarak kapanır: sonraki çağrılar 409 AlreadySetUp döner. Health check artık Healthy yanıtını verir.

4. Giriş yapın#

curl -X POST http://localhost:9716/generate-token \
	-H 'X-Ertis-Alias: <membership_id>' \
	-H 'Content-Type: application/json' \
	-d '{ "username": "admin", "password": "<password>" }'

{
	"token_type": "Bearer",
	"access_token": "eyJhbGciOiJIUzI1NiIs…",
	"expires_in": 3600,
	"refresh_token": "eyJhbGciOiJIUzI1NiIs…",
	"refresh_token_expires_in": 86400,
	"created_at": "2026-01-01T12:00:00Z"
}

username alanı e-posta adresini de kabul eder.

5. API'yi çağırın#

curl http://localhost:9716/me -H 'Authorization: Bearer <access_token>'

curl 'http://localhost:9716/memberships/<membership_id>/users?limit=10&with_count=true' \
	-H 'Authorization: Bearer <access_token>'

Uygulama da aynı endpoint'leri, id'si ve secret'ından oluşan bir Basic token ile çağırabilir:

curl 'http://localhost:9716/memberships/<membership_id>/users' \
	-H 'Authorization: Basic <application_id>:<application_secret>'

Sonraki adımlar#

• Kullanıcı modelinizi Kullanıcı Tipleri ile tasarlayın.
• Kullanıcılarınız için Roller sayfasında roller oluşturun ve yetki modelini öğrenin.
• Aktivasyon ve şifre sıfırlama e-postalarını Mail Hook'lar ve Hesap Kurtarma ile yapılandırın.
• Kendi servislerinizi .NET SDK ile koruyun.