API Gateway:Configure custom authentication and authorization

Arka plan

Sunucular, harici olarak erişime açılan API'ler için iletişimi güvence altına almak amacıyla genellikle istemci isteklerinde bulunan kimlik bilgilerine (belirteçler) güvenir.

• Belirteçleriniz JSON Web Belirteçleri (JWT) ise, merkezi bir kimlik doğrulama hizmetine erişmeden genel anahtar kullanarak imzalarını herhangi bir yerde doğrulayabilirsiniz.

• Belirteçleriniz özel bir format kullanıyorsa, sunucunun kimlik doğrulama ve yetkilendirme kontrollerini yapmak için merkezi bir hizmeti çağırması gerekir. Bu süreç, API iletişimini güvence altına alır. Cloud-native API Gateway bu özel kimlik doğrulama ve yetkilendirme yöntemini destekler.

Aşağıdaki örnek, bir Cloud-native API Gateway'in özel bir kimlik doğrulama hizmetiyle entegre edilmesinden sonraki istek işleme akışını göstermektedir.

1. İstemci, oturum açma işlemi gibi bir kimlik doğrulama isteğini ağ geçidine gönderir.

2. Ağ geçidi, kimlik doğrulama isteğini doğrudan kimlik doğrulama hizmetine iletir.

3. Kimlik doğrulama hizmeti, istekteki kullanıcı adı ve parola gibi kimlik bilgilerini doğrular. Doğrulama başarılı olduğunda, ağ geçidine bir belirteç döndürür; ağ geçidi de bu belirteci istemciye iletir.

4. İstemci, sipariş vermek için /order yoluna yapılan istek gibi bir iş isteği gönderir. İstek, başarılı kimlik doğrulamadan sonra verilen belirteci içerir.

5. Ağ geçidi, orijinal iş isteğinden yolu (sorgu parametreleri dahil), HTTP yöntemini (GET veya POST gibi) ve belirteci yakalar. Ağ geçidi bu bilgileri kullanarak yeni bir istek oluşturur ve bunu yetkilendirme için özel kimlik doğrulama hizmetine gönderir. Ağ geçidi konsolunda, belirtecin bulunduğu HTTP üstbilgisini yapılandırmanız gerekir. Orijinal istek gövdesinin de dahil edilmesine izin verebilirsiniz.

   Özel kimlik doğrulama hizmetinin kimlik doğrulama API'si /validateToken ise, ağ geçidi orijinal iş isteğinin yolunu kimlik doğrulama API'sinin yoluna ekleyerek gerçek yetkilendirme isteği yolunu (/validateToken/order) oluşturur.

6. Kimlik doğrulama hizmeti yetkilendirme isteğini aldığında, belirteci doğrulayabilir ve istemcinin orijinal istek yoluna erişim izninin olup olmadığını kontrol edebilir.

   • Kimlik doğrulama hizmetiniz yanıtındaki HTTP durum kodunu değiştirebiliyorsa, yetkilendirme sonucunu belirtmek için durum kodunu kullanabilirsiniz.

     • 200 HTTP durum kodu, belirtecin geçerli olduğunu ve arka uç kaynağına erişim yetkisi bulunduğunu gösterir. Ağ geçidi daha sonra orijinal iş isteğini korunan arka uç hizmetine iletir. Arka uçtan yanıtı aldıktan sonra, ağ geçidi bunu istemciye ileterek sipariş verme işlemini tamamlar.

     • 401 veya 403 HTTP durum kodu, belirtecin geçersiz olduğunu veya arka uç kaynağına erişim yetkisi bulunmadığını gösterir. Ağ geçidi, kimlik doğrulama hizmetinin yanıtını derhal istemciye döndürerek sipariş verme işleminin başarısız olmasına neden olur.

   • İş kısıtlamaları nedeniyle kimlik doğrulama hizmetinizin her zaman 200 HTTP durum kodu döndürmesi gerekiyorsa, yerleşik HTTP üstbilgisi olan x-mse-external-authz-check-result öğesini kullanabilirsiniz.

     • Kimlik doğrulama hizmeti, x-mse-external-authz-check-result üstbilgisi true olarak ayarlanmış bir yanıt döndürürse, belirtecin geçerli olduğu ve arka uç kaynağına erişim iznine sahip olduğu anlamına gelir. Ağ geçidi daha sonra orijinal isteği korunan arka uç hizmetine iletir ve yanıtı istemciye geri ileterek sipariş verme işlemini tamamlar.

     • Kimlik doğrulama hizmeti, x-mse-external-authz-check-result üstbilgisi false olarak ayarlanmış bir yanıt döndürürse, belirtecin geçersiz olduğu veya arka uç kaynağına erişim iznine sahip olmadığı anlamına gelir. Ağ geçidi, kimlik doğrulama hizmetinin yanıtını doğrudan istemciye döndürerek sipariş verme işleminin başarısız olmasına neden olur.

Özel kimlik doğrulama kuralı oluşturma

1. API Gateway konsolu adresinde oturum açın.

2. Sol gezinme bölmesinde, Cloud-native API Gateway > Instance seçeneklerine tıklayın. Üst gezinme çubuğundan bir bölge seçin.

3. Instance sayfasında, hedef ağ geçidi örneğinin adına tıklayın.

4. Sol gezinme bölmesinde, Security Management > Global Authentication seçeneklerine tıklayın.

5. Global Authentication sayfasında, Create Authentication seçeneğine tıklayın. Create Authentication panelinde parametreleri yapılandırın ve OK seçeneğine tıklayın.

   Parametre	Not: Custom Authentication Service
   Enable	Cloud-native API Gateway için kimlik doğrulama ve yetkilendirmeyi etkinleştirip etkinleştirmeyeceğinizi belirtir.
   Authentication Name	Kimlik doğrulama ve yetkilendirme kuralı için özel bir ad.
   Authentication Type	Custom Authentication Service seçeneğini seçin.
   Authentication Service	Kimlik doğrulama ve yetkilendirme için kullanılan arka uç hizmeti. Hizmet yönetimine hizmet ekleyebilirsiniz. Daha fazla bilgi için bkz. Hizmet ekleme. Not Yalnızca HTTP protokolünü kullanan hizmetler desteklenir. Dubbo gibi diğer protokolleri kullanan hizmetler desteklenmez. Bir Kubernetes Service birden çok bağlantı noktasına sahipse, varsayılan olarak ilk bağlantı noktası kullanılır. Farklı bir bağlantı noktası kullanmak istiyorsanız, Container Service for Kubernetes (ACK) içinde yalnızca hedef bağlantı noktasını gösteren ek bir Kubernetes Service oluşturun.
   Authentication API	Kimlik doğrulama hizmeti tarafından sağlanan API'nin yolu. Ağ geçidi bu yolu önek eşleştirmesi için kullanır. Örneğin, kimlik doğrulama hizmetiniz Spring MVC üzerine kurulmuşsa, /check kimlik doğrulama API'sini gösteriyorsa ve /check/ ile başlayan yollara yönelik istekleri işlemek istiyorsanız, aşağıdaki gibi yapılandırabilirsiniz: @RequestMapping("/check/") public ResponseEntity<RestResult<String>> check(){}
   Token Location	İstek üstbilgisindeki belirtecin konumu, genellikle Authorization veya Cookie. Belirteç konumunu ayarlamak için listeden Select seçeneğini kullanabilir veya Add Manually seçeneğiyle manuel olarak ekleyebilirsiniz.
   Allowed Headers in Authentication Rrequest	Orijinal istemci isteğinden hangi üstbilgilerin kimlik doğrulama hizmetine iletileceğini belirtir. Not Host, Method, Path ve Content-Length üstbilgileri varsayılan olarak dahildir ve manuel olarak eklenmesine gerek yoktur.
   Allowed Headers in Authentication Response	Kimlik doğrulama hizmetinin yanıtından hangi üstbilgilerin arka uç hizmetine gönderilen isteğe ekleneceğini belirtir. Not Burada belirtilen bir üstbilgi istemci isteğinde zaten varsa, ağ geçidi değerini üzerine yazar.
   Allow Body in Authentication Request	Allow Body in Authentication Request: Orijinal istemci isteğinin gövdesini kimlik doğrulama hizmetine gönderilen isteğe dahil eder. Maximum Body Size: İletilebilecek maksimum istek gövdesi boyutu (bayt cinsinden).
   Timeout Period	Kimlik doğrulama hizmetinden yanıt beklemek için maksimum süre (saniye cinsinden). Varsayılan: 10.
   Mode	Kimlik doğrulama hizmeti kullanılamadığında izlenecek davranışı belirtir. Loose Mode ve Strict Mode desteklenir. Loose Mode kullanmanızı öneririz. Loose Mode: Kimlik doğrulama hizmeti kullanılamıyorsa (örneğin, bağlantı başarısız olursa veya hizmet 5xx hatası döndürürse), ağ geçidi istemci isteğinin ilerlemesine izin verir. Strict Mode: Kimlik doğrulama hizmeti kullanılamıyorsa (örneğin, bağlantı başarısız olursa veya hizmet 5xx hatası döndürürse), ağ geçidi istemci isteğini reddeder.
   Simple Conditions	Authorization yanındaki Simple Conditions seçeneğine tıklayın. Bu mod, Whitelist Mode ve Blacklist Mode seçeneklerini destekler. Whitelist Mode: İzin listesindeki ana bilgisayarlar ve yollarla eşleşen istekler doğrulamayı atlayabilir. Diğer tüm ana bilgisayarlar ve yollar doğrulama gerektirir. Blacklist Mode: Engel listesindedeki ana bilgisayarlar ve yollarla eşleşen istekler doğrulama gerektirir. Diğer tüm ana bilgisayarlar ve yollara doğrudan erişilebilir. İstek alan adı, yolu ve üstbilgilerine göre koşulları ayarlamak için Rule Condition seçeneğine tıklayın. Domain Name: İstenen ana bilgisayar alan adı. Path: İstenen API yolu. Path Match Condition: Yol, tam eşleşme, önek eşleşmesi veya düzenli ifade eşleşmesi kullanılarak eşleştirilebilir. Exact Match: Tam bir yol girin, örneğin /app/v1/order. Prefix Match: Yıldız işareti () ile biten bir yol öneki girin. Örneğin, /app ile başlayan tüm istekleri eşleştirmek için /app/ girin. Regular Expression Match: Söz dizimi Google RE2 standardını takip eder. Daha fazla bilgi için bkz. RE2 Syntax. Case sensitive: Yol eşleştirmesini büyük/küçük harfe duyarlı hale getirir. Header: İsteğin üstbilgisi. Birden çok üstbilgiyi yapılandırmak için Request Header seçeneğine tıklayın. Üstbilgiler üzerinde mantıksal VE işlemi uygulanır. HeaderKey: Üstbilgi alanının adı. Condition: Üstbilgi için eşleşme koşulu. Equals To: Belirtilen üstbilginin değeri girilen değere eşittir. Does Not Equal To: Belirtilen üstbilginin değeri girilen değere eşit değildir. Exists: Belirtilen üstbilgi istekte mevcuttur. Does Not Exist: Belirtilen üstbilgi istekte mevcut değildir. Contains: Belirtilen üstbilginin değeri girilen değeri içerir. Excludes: Belirtilen üstbilginin değeri girilen değeri içermez. Prefix: Belirtilen üstbilginin değeri girilen değerle başlar. Suffix: Belirtilen üstbilginin değeri girilen değerle biter. Regular Expression Match: Belirtilen üstbilginin değeri girilen düzenli ifadeyle eşleşir. Söz dizimi Google RE2 standardını takip eder. Daha fazla bilgi için bkz. RE2 Syntax. Value: Üstbilgi alanıyla eşleştirilecek değer.
   Complex Conditions	Authorization yanındaki Complex Conditions seçeneğine tıklayın. Bu mod, Envoy'un permission veri yapısının YAML yapılandırmasını kullanarak yetkilendirme kuralları tanımlamanıza olanak tanır. Birleştirilmiş VE, VEYA ve DEĞİL mantığı içeren kurallar oluşturabilirsiniz. Ağ geçidi, yapılandırılan koşullarla eşleşen istekleri kimlik doğrulama için gönderir. Eşleşmeyen istekler kaynaklara doğrudan erişebilir. Not permission veri yapısı alanlarının tam açıklaması için resmi Envoy belgelerine bakın. Yapılandırma örnekleri için bkz. Karmaşık koşul yetkilendirme örnekleri.

   Global Authentication sayfasına dönün. Yeni kural listede görünüyorsa, başarıyla oluşturulmuştur.

Kimlik doğrulama hizmetlerini görüntüleme ve yönetme

1. API Gateway konsolu adresinde oturum açın.

2. Sol gezinme bölmesinde, Cloud-native API Gateway > Instance seçeneklerine tıklayın. Üst gezinme çubuğundan bir bölge seçin.

3. Instance sayfasında, hedef ağ geçidi örneğinin adına tıklayın.

4. Sol gezinme bölmesinde, Security Management > Global Authentication seçeneklerine tıklayın.

5. Authentication sayfasında, hedef kimlik doğrulama kuralını bulun ve Actions sütunundaki Description seçeneğine tıklayın. Basic Information ve Authentication Configuration bölümlerini görüntüleyebilir ve Authorization Information bölümünü yönetebilirsiniz.

   Authentication Configuration bölümü; Authentication Service, Authentication API, Token Location, Timeout Period, Mode (örneğin Loose Mode), Allow Body in Authentication Request, Allowed Headers in Authentication Request ve Allowed Headers in Authentication Response gibi alanları içerir. Authorization Information bölümü geçerli modu (örneğin Whitelist Mode) görüntüler. Birden çok kural koşulu arasında mantıksal "VEYA" ilişkisi bulunur. Yetkilendirme kuralı listesi; Request Domain, Request Path Matchers, case-sensitive ve Request Header Matchers gibi sütunlar içerir.

   Authorization Information bölümünde, Create Authorization seçeneğine tıklayın. Görüntülenen iletişim kutusunda Request Domain Name ve Request Path bilgilerini girin, bir Match Mode seçin ve yetkilendirme kuralını eklemek için OK seçeneğine tıklayın.

İlgili işlemler

• Kimlik doğrulama ve yetkilendirmeyi etkinleştirme: Global Authentication sayfasında, hedef kuralı bulun ve Actions sütunundaki Enable seçeneğine tıklayarak etkinleştirin.

• Kimlik doğrulama ve yetkilendirmeyi devre dışı bırakma: Global Authentication sayfasında, hedef kuralı bulun ve Actions sütunundaki Close seçeneğine tıklayarak devre dışı bırakın.

• Kimlik doğrulama ve yetkilendirmeyi düzenleme: Global Authentication sayfasında, hedef kuralı bulun ve Actions sütunundaki Edit seçeneğine tıklayarak yapılandırmasını değiştirin.

• Kimlik doğrulama ve yetkilendirmeyi silme: Global Authentication sayfasında, hedef kuralı bulun ve Actions sütunundaki Delete seçeneğine tıklayarak kaldırın.

Karmaşık koşul yetkilendirme örnekleri

permissions:
# and_rules: Triggers authentication if all the following rules are met.
- and_rules:
    rules:
      - url_path:
          # Path prefix matching.
          path:
            prefix: /
      - header:
          # Regular expression matching.
          safe_regex_match:
            regex: "(exampleA\\.com|exampleB\\.com)"
          # The domain name can be obtained from the ":authority" header,
          # according to the HTTP pseudo-header specification.
          name: ":authority"

permissions:
# or_rules: Triggers authentication if any of the following rules are met.
- or_rules:
    rules:
      # and_rules: This rule is met only if all the following sub-rules are met.
      # Rule 1
      - and_rules:
          rules:
            - url_path:
                path:
                  exact: /api/appc/bbb/ccc
            - header:
                exact_match: "exampleB.com"
                name: ":authority"
      # Rule 2                
      - and_rules:
          rules:
            - url_path:
                path:
                  exact: /api/appc/ccc/ddd
            - header:
                exact_match: "exampleB.com"
                name: ":authority"
      - and_rules:
          rules:
            # Rule 3
            - url_path:
                path:
                  prefix: /api/
            # not_rule: Matches if the nested rule does not match.
            # Rule 4
            - not_rule:
                url_path:
                  path:
                    exact: /api/appa/bbb
            # Rule 5
            - not_rule:
                url_path:
                  path:
                    exact: /api/appb/ccc                                
            - header:
                exact_match: "exampleA.com"
                name: ":authority"                                
      - and_rules:
          rules:
            # Rule 6
            - url_path:
                path:
                  prefix: /
            # not_rule: Matches if the nested rule does not match.
            # Rule 7
            - not_rule:
                url_path:
                  path:
                    exact: /api/appa/bbb
            # Rule 8
            - not_rule:
                url_path:
                  path:
                    exact: /api/appb/ccc
            # Rule 9
            - not_rule:
                url_path:
                  path:
                    prefix: /api/appc/                                         
            - header:
                exact_match: "exampleB.com"
                name: ":authority"