Ana içeriğe geç

GMU BASKET API

Teknolojiler​

Basket projesinde bakım/yönetim/geliştirme kolaylığı açısından GMU çatısı altındaki projeler ile aynı teknolojiler tercih edilmiştir.

  • Backend (Api) Asp.Net Web Api projesi, docker imajı olarak (redhat veya ubuntu) teslim edilmektedir. K8s/Openshift ortamında çalıştırılması önerilir.

  • Backoffice NodeJS projesi, docker imajı olarak (redhat veya ubuntu) teslim edilmektedir. K8s/Openshift ortamında çalıştırılması önerilir.

  • Sql Server 2019+ (migration: otomatik). Halihazırdaki GMU sql server sunucuları üzerinde yeni bir veritabanı açılarak kullanılabilir.

  • ELK (Loglama/APM). GMU projeleri ile aynı ELK konfigürasyonlarını (auth vb.) destekler.

  • Redis (Keşleme). Halihazırdaki GMU redis sunucuları kullanılabilir.

  • Auth seçenekleri

    • keycloak (veritabanı tercihi sql server)
    • müşterinin kendi yazacağı oauth2 standardına uygun entegrasyon
    • herhangi bir auth server kullanmadan sql serverda da kullanıcıları tutabilmekte, şuan bu özellik sadece basic auth ile destekleniyor, daha sonra talebe göre jwt auth için geliştirme yapılabilir.

  • Opsiyonel Microsoft Dynamics CRM ile entegrasyon

  • Opsiyonel Azure ServiceBus ile entegrasyon

Kurulum​

Uygulama .net 7 docker imajı.

İhtiyaç duyulan tüm environment variable değerleri aşağıda verilmiştir. Zorunlu değer olanların sonunda '*' ibaresi vardır.

  • ASPNETCORE_ENVIRONMENT: Çalışma ortamı şu değerlere sahip olabilir: Development, Test, Staging, Production. Varsayılan değer: Development

  • DbConnectionString *: Veritabanı erişim bilgileri. Format: "Server={server};Database={db};User Id={username};Password=;TrustServerCertificate=true"

  • DbPassword *: Veritabanı erişim şifresi. Zorunlu, k8s/openshift'de secret olarak saklanması önerilir.

  • ConsoleLogLevel *: Console loglarının en düşük seviyesi. Değer girilmez ise default değer Information'dır. Seviye sırasına göre şunlardan biri olabilir: "Verbose", "Debug", "Information", "Warning", "Error", "Fatal"

  • Secret *: Konfigürasyon verilerini veritabanında kriptolu tutmak için gerekli secret. Zorunlu, alfanumerik, k8s/openshift'de secret olarak saklanması önerilir. Bu değer sonradan kesinlikle değiştirilmemelidir, aksi taktirde eski kriptolu verilere erişilemez. Örn : C4E47AF5CBF397C864DD7B5374E914F9

  • EkuUpdateDay: Yazarkasa Ekü bilgilerinin kaç gün aralıklarla güncelleneceği bilgisini belirtir.

  • ProductAndRvcSyncEnabled: Basket uygulamasına gönderilen çeklerin içinde bulunan ürünlerin ve Gelir Merkez'i bilgisinin önceden sisteme kaydedilip kaydedilmemesi gerektiğini belirtir(True/False). Varsayılan False.

  • GmuConnection__Url: Basket Uygulamasının GMU Entegrasyonu olacak ise gmu-api servis url'i.

  • GmuConnection__Username: GMU Entegrasyonu için ortam bazlı değişkenlik gösteren GMU kullanıcı adı.

  • GmuConnection__Password: GMU Entegrasyonu için ortam bazlı değişkenlik gösteren GMU şifresi.

  • Redis__ConnectionString: Redis bağlantı bilgileri. Format: "addres:port,defaultDatabase=1,password=" Birden fazla adres desteği vardır: "addres1:port1,addres2:port2,defaultDatabase=1,password=" vb.

  • Redis__CertificateFullPath: Redis Client'ın TLS desteği için kullanacağı sertifikanın dosya yolu. Eğer boş bırakılır ise TLS olmadan bir bağlantı kurulur.

  • Redis__Password: Redis şifresi.

  • CrmConnection__Url: Basket Uygulamasının CRM Entegrasyonu olacak ise CRM servis url'i.

  • CrmConnection__Username: CRM Entegrasyonu için kullanıcı adı.

  • CrmConnection__Password: CRM Entegrasyonu için şifre.

  • Auth__DisableKeycloak: Ortamda keycloak kullanılmayacaksa burası true yapılmalı, değer verilmezse varsayılan değeri false. Bu alan false yapıldığında Auth__TokenUrl, Auth__EndpointUrl, Auth__Username, Auth__Password konfigürasyonları doldurulmalı.

  • Auth__TokenUrl: Keycloak Token alma adresi, Auth__DisableKeycloak=true değilse burası zorunlu. Ör: https://gmu-posdevelopment.protel.com.tr/auth/realms/master/protocol/openid-connect/token

  • Auth__EndpointUrl: Uygulama için keycloakda açılan realmı da içeren Keycloak Endpoint adresi, Auth__DisableKeycloak=true değilse burası zorunlu. Ör: https://gmu-posdevelopment.protel.com.tr/auth/admin/realms/okc

  • Auth__Username: Keycloak erişim kullanıcı adı (keycloakda açılan usera ait), Auth__DisableKeycloak=true değilse burası zorunlu

  • Auth__Password: Keycloak erşim password (keycloakda açılan usera ait), Auth__DisableKeycloak=true değilse burası zorunlu

  • Auth__MetadataAddress: Opsiyonel ancak bu veya Auth__IssuerSigningKeyJwkAddress den biri dolu olmalı. JWT auth için gerekli imza anahtarı buradan alınır. ör: http://auth-service:8080/auth/realms/gmupos/.well-known/openid-configuration

  • Auth__Issuer *: jwt auth issuer, her koşulda zorunlu. ör: https://gmu-posdevelopment.protel.com.tr/auth/realms/okc

  • Auth__Audiences__0 *: Auth Server Audiences, her koşulda zorunlu. Ör: "okcapi",.. Birden fazla , audience varsa Auth__Audiences__0, Auth__Audiences__1,... şeklinde verilmeli

  • Auth__IssuerSigningKeyJwkAddress: Opsiyonel ancak bu veya Auth__MetadataAddress dan biri dolu olmalı. JWT auth için gerekli imza anahtarı buradan alınır. Örnekteki gibi URL olarak verilebildiği gibi http://192.168.100.25:30003/auth/realms/okcapi/protocol/openid-connect/certs direkt json olarak da verilebilir. Birden fazla jwks desteği olmadığından dizi şeklinde değil tek jwk verilmeli.

  • Elk__ConnectionString: ELK loglama yapılacaksa doldurulur. Ör: http://elk-elasticsearch:9200

  • Elk__APMConnectionString: ELK'nın APM özelliği kullanılacaksa doldurulur. Ör: http://apm-elasticsearch:8200

  • Elk__ApiKey: ELK tarafında Api Key ile authentication isteniyorsa, buraya istenilen değer yazılmalıdır. Aksi takdirde çağrılar 401 UnAuthorized olarak sonuçlanır.

  • Elk__AuthUsername: ELK tarafında Username/Password ile (Basic) authentication isteniyorsa, buraya ilgili username bilgisi yazılmalıdır. Eğer Password alanı da dolu değilse Basic Auth konfigürasyonu yapılmaz. ApiKey Authentication bilgileri de dolu ise, öncelik ApiKey Authentication'a verilir.

  • Elk__AuthPassword: ELK tarafında Username/Password ile (Basic) authentication isteniyorsa, buraya ilgili password bilgisi yazılmalıdır. Eğer Username alanı da dolu değilse Basic Auth konfigürasyonu yapılmaz. ApiKey Authentication bilgileri de dolu ise, öncelik ApiKey Authentication'a verilir.

  • Elk__IndexName: Basket Loglarının ELK tarafında hangi Index'e atılması gerektiğini belirtir.Örn: "logstash-{0:yyyy.MM.dd}". Eğer değer girilmezse Basket tarafında default değer verilir. Default değer : "okcapi-log-{0:yyyy.MM.dd}"

  • ELK__TemplateName: Basket Loglarının ELK tarafında hangi Template'e atılması gerektiğini belirtir. Örn: "serilog-events-template". Eğer değer girilmezse Basket tarafında default değer verilir. Default değer : "serilog-okcapi-template"

  • Elk__IndexAliases__0: ELK için hangi index aliaslarının kullanılacağını belirtir. Aliaslar virgül ile ayrılmalıdır. Örn: "alias1,alias2,alias3". Boş bırakılabilir, varsayılan değeri de "boştur.

  • Elk__LogLevel: ELK loglarının en düşük seviyesi. Değer girilmez ise default değer Information'dır. Seviye sırasına göre şunlardan biri olabilir: "Verbose", "Debug", "Information", "Warning", "Error", "Fatal"

  • ServiceBusConnection__TopicEnabled: Basket Uygulamasının Azure Service Bus kullanıp kullanmayacağı bilgisi. (True/False)

  • ServiceBusConnection__MicrosTopicName: Azure Service Bus aktif ise Micros'a özel kullanılacak topic bilgisi.

  • ServiceBusConnection__SimpraTopicName: Azure Service Bus aktif ise Simpra'ya özel kullanılacak topic bilgisi.

  • ServiceBusConnection__ConnStr: Azure Service Bus erişim bilgisi.

  • ServiceBusConnection__ClientConnectionString: Azure Service Bus Client'a özel erişim bilgisi. Client erişim bilgisin sadece "Read" yetkisine sahip olması tavsiye edilir.

  • JobDbConnectionString: Hangfire veritabanı bağlantı bilgileri. Format: Server={server};Database={db};User Id={uid};Password=

  • JobDbPassword: Hangfire veritabanı şifresi.

  • EnableTokenBlacklisting: Auth tokenlar için kara liste özelliğini aktif eder. Aktif olrak kullanabilmek için Redis__ConnectionString ve Redis__Password dolu olmalıdır. Varsayılan değeri false'dir.

  • HealthcheckDbConnectionString: Healthcheck veritabanı bağlantı bilgileri. Format: Server=;Database=;User Id=;Password=

  • HealthcheckDbPassword: Healthcheck veritabanı şifresi.

  • Mail__DbSupportEmails: Veritabanı erişim hatası gibi veritabanı ile ilgili hata durumlarında uyarı e-postalarının kimlere atılacağı. Noktalı virgül ile ayrılarak birden fazla adres girilebilir.

  • Mail__DevOpsSupportEmails: ELK erişim hatası gibi devops ile ilgili hata durumlarında uyarı e-postalarının kimlere atılacağı. Noktalı virgül ile ayrılarak birden fazla adres girilebilir.

  • Mail__SystemEmailSender: Sistem maillerini gönderecek adres. Varsayılan değeri: "gmubasket-donotreply@protel.com.tr"

  • Mail__Smtp__Server: SMTP sunucu bilgisi. Boş bırakılabilir. Girilmez ise SMTP plugin servisi çalışmaz.

  • Mail__Smtp__EnableSsl: SMTP mail gönderiminin SSL ile mi yapılacağını belirtir

  • Mail__Smtp__ServerPort: SMTP sunucu port bilgisi

  • Mail__Smtp__Username: SMTP bağlantısı için kullanıcı adı. SMTP sunucucu tarafında zorunlu değil ise boş bırakılabilir.

  • Mail__Smtp__Password: SMTP bağlantısı için kullanıcı şifresi. SMTP sunucucu tarafında zorunlu değil ise boş bırakılabilir.

  • ScopePermissionEnabled: Yetki kontrolünün yapılıp yapılmayacağı bilgisini tutar. true/false. Varsayılan olarak falsedur

  • ExposeErrorDetails: true/false.Eğer true verilir ise hatalı çağrılarda response kısmındaki "Details" ve "StackTrace" dolu olarak gelir. false yapılır ise bu alanlar response'da null gözükür. Prod ortamında güvenlik sebebiyle false yapılmalıdır. Geliştirme ortamlarında true yapılması önerilir.

  • HmacSecret: Android client GMU Rest Api ile mesajlaşma esnasında MITM (Man In The Middle) attack'a karşı HMAC (Keyed-Hash Message Authentication Code) kullanır. Buraya girilen secret ile Android SDK'ya init aşamasında pasgeçilen secret aynı olmalı. Secret herhangi bir random hex generator ile vb oluşturulabilir. Bir işletici kuruluş bazında her ortamda aynı değere sahip olmalıdır.

  • DisableHmacAuth: true/false. Varsayılan: false. Değer girilmemiş ise veya false seçilmiş ise HmacAuth kontrolu var eğer true girilmiş işe HmacAuth kontrolune bakılmıyor.

  • DisableOptions: true/false. Varsayılan: false. Değer girilmemiş ise veya false seçilmiş ise OPTIONS çağrıları aktif edilir. Eğer true girilmiş ise OPTIONS çağrıları engellenir.

İlk Kurulum Sonrası SüperAdmin Tanımı:​

  • İlk kurulum sonrası uygulama ayağa kaldırılarak db-migration'ın çalışması sağlanır. Bu aşamada Basket tabloları oluşur.

  • Elle Authorization Server''ında bir superadmin ve entegrasyon kullanıcısı oluşturulmalıdır.

    • Burada oluşturulan kullanıcıların id'si (guid formatında) aşağıdaki db-scriptdeki <SUPER_ADMIN_AUTH_SERVER_ID> ve <INTEGRATION_USER_AUTH_SERVER_ID> geçen yerlere girilmelidir.

    Basket veritabanında ilk kurulum sonrası çalıştırılacak db-script:​

ALTER TABLE dbo.[User] SET (SYSTEM_VERSIONING = OFF)

insert into dbo.[User] (IntegrationId, Username, PasswordHash, Role, FirstName, LastName) values
    ('<SUPER_ADMIN_AUTH_SERVER_ID>', N'okcapi@protel.com.tr', null, N'Admin', N'Okc', N'Admin');
        
insert into dbo.[User] (IntegrationId, Username, PasswordHash, Role, FirstName, LastName) values
    ('<INTEGRATION_USER_AUTH_SERVER_ID>', N'okcapiint@protel.com.tr', null, N'Integration', N'Okc', N'Integration');

update dbo.[User] set ModifiedBy = (select Id from dbo.[User] where Username = N'okcapi@protel.com.tr') where ModifiedBy is null;

alter table dbo.[UserHistory] alter column ModifiedBy bigint NOT NULL;
alter table dbo.[User] alter column ModifiedBy bigint NOT NULL;

alter table dbo.[User] set (SYSTEM_VERSIONING = ON (HISTORY_TABLE = dbo.UserHistory));

Harici Auth Sistemleri ile Entegrasyon:​

  • Auth__DisableKeycloak konfigürasyonu True yapılmalı, bu senaryoda şu konfigürasyonlar kullanılmayacaktır: Auth__TokenUrl, Auth__EndpointUrl, Auth__Username, Auth__Password.

  • Harici auth sistemi token üretirken userid ve rol bilgisini keycloak'daki implementasyon ile aynı formatta vermelidir.

    • Örneğin: "sub" claim'ine userid (guid olmalı).
    • Realm_access claimi altına liste olarak rolleri eklemeli (şu an Admin, Integration, POS ve PaymentTerminal rolleri yer almaktadır.)
En son tarihinde güncellendi