1.1.5.5. Custom URL Authenticator#

Bu doküman, HvlAuthCustomUrlAuthenticatorImpl sınıfını kullanarak özelleştirilmiş bir URL üzerinden kimlik doğrulama akışını nasıl yapılandırabileceğinizi ve kullanabileceğinizi açıklamaktadır. Bu entegrasyon, dış REST servisi ile POST ( JSON/Form) ve GET istekleri kullanarak kimlik doğrulama işlemi yapılmasına olanak tanır.

Kullanım Amaçları#

HvlAuthCustomUrlAuthenticatorImpl, kullanıcı kimlik doğrulama isteklerini belirttiğiniz bir dış servis URL'sine ileterek doğrulama işlemlerini gerçekleştirir. Bu servis, genel olarak bir OpenID Connect veya OAuth sunucuya bağlanmak için kullanılır. Standart kimlik doğrulama yöntemlerinde yer almayan özel doğrulama ihtiyaçlarınızı karşılamak için ideal bir çözümdür.

Ayarlanabilir Parametreler#

Header Forwarding (İstek Header'larını İletme)#

Custom Identity Provider'a yapılan kimlik doğrulama isteklerine, gelen HTTP isteğindeki belirli header'ları taşıma özelliği mevcuttur. Bu özellik, dış kimlik doğrulama servisinin ek bağlamsal bilgilere (örn: correlation ID, session bilgisi, tenant bilgisi vb.) ihtiyaç duyduğu senaryolarda kullanılır.

Kullanım Senaryoları#

• Oturum Takibi: session_id veya token gibi header'ların dış servise iletilmesi
• İstek İzleme: X-Correlation-Id veya X-Request-Id gibi izleme header'larının aktarılması
• Multi-Tenant Yapılar: X-Tenant-Id gibi tenant bilgilerinin dış servise iletilmesi
• Özel Kimlik Doğrulama: Dış servisin gerektirdiği özel header'ların aktarılması

Konfigürasyon Örnekleri#

Environment Variable ile:

# Tek header
export CUSTOM_AUTH_FORWARD_HEADERS=token

# Birden fazla header (virgülle ayrılmış)
export CUSTOM_AUTH_FORWARD_HEADERS=token,session_id

# Daha fazla header
export CUSTOM_AUTH_FORWARD_HEADERS=token,session_id,X-Correlation-Id,X-Tenant-Id

YAML Konfigürasyonu (Default Değerli):

hvl:
  oauth:
    auth:
      custom-ip-authenticator:
        request:
          forward-headers: ${CUSTOM_AUTH_FORWARD_HEADERS:token,session_id}

YAML Konfigürasyonu (Liste Formatında):

hvl:
  oauth:
    auth:
      custom-ip-authenticator:
        request:
          forward-headers:
            - token
            - session_id
            - X-Correlation-Id

Docker/Docker Compose Kullanımı:

# docker-compose.yml
services:
  auth-service:
    environment:
      - CUSTOM_AUTH_FORWARD_HEADERS=token,session_id,X-Correlation-Id

Önemli Notlar#

Doğrulama#

Uygulama başlatıldığında, forward headers konfigürasyonu log'larda görüntülenir:

INFO  - Request Configuration:
INFO  -   Forward Headers (from incoming request): [token, session_id]

Mapping Yapılmasında Fayda Olacak Keysis Hata Kodları#

Dış servis hata kodu için keycloak örnek verilmiştir. Siz bağlantı kuracağınız custom authentication server'a ait error kodu girmelisiniz.

Angular Uygulaması Konfigürasyonu#

hvl-ng-framework-theme ile geliştirilmiş Angular uygulamalarında, login ekranında yapılacak istemlerin önceden belirlenmiş bir Custom Identity Provider (CUSTOM_IP) uygulamasına yönlendirilmesi gerekiyorsa, config.json dosyasında supportedAuthenticationTypes ayarı yapılmalıdır:

"supportedAuthenticationTypes": ["CUSTOM_IP"]

Eğer supportedAuthenticationTypes sadece bir değer içeriyorsa, sistem bu değere uygun olarak otomatik çalışır ve kullanıcının seçim yapmasına gerek kalmaz.

Ancak, supportedAuthenticationTypes değeri şöyle bir liste gibi birden fazla seçenek içeriyorsa:

"supportedAuthenticationTypes": ["DB", "LDAP", "CUSTOM_IP"]

Bu durumda, kullanıcıya bir açılır menü sunulacak ve seçim yapması istenecektir. Listede ilk sırada yer alan seçenek varsayılan olarak seçili olur.

Örnek Tam Konfigürasyon#

hvl:
  oauth:
    auth:
      custom-ip-authenticator:
        timeout: ${CUSTOM_AUTH_TIMEOUT:3000}
        read-timeout: ${CUSTOM_AUTH_READ_TIMEOUT:3000}
        endpoint:
          url: ${CUSTOM_AUTH_URL:http://localhost:8089/realms/master/protocol/openid-connect/token}
          method: ${CUSTOM_AUTH_METHOD:POST}
        headers:
          Content-Type: ${CUSTOM_AUTH_CONTENT_TYPE:application/x-www-form-urlencoded}
          Accept: ${CUSTOM_AUTH_ACCEPT_HEADER:application/json}
          User-Agent: ${CUSTOM_AUTH_USER_AGENT:HvlAuthProxy/1.0}
        request:
          username-field: ${CUSTOM_AUTH_USERNAME_FIELD:username}
          password-field: ${CUSTOM_AUTH_PASSWORD_FIELD:password}
          additional-fields:
            grant_type: "password"
            client_id: "admin-cli"
          use-query-params: ${CUSTOM_AUTH_USE_QUERY_PARAMS:false}
          forward-headers: ${CUSTOM_AUTH_FORWARD_HEADERS:token,session_id}
        success:
          http-status: [200, 201, 202]
        error:
          error-field: ${CUSTOM_AUTH_ERROR_FIELD:error}
          error-code-mapping:
            invalid_grant: ${ERROR_MAPPING_USER_EXPIRED:OAUTH-AUTH_0003}
            wrong_credentials: ${ERROR_MAPPING_WRONG_CREDENTIALS:OAUTH-AUTH_0001}
            user_locked: ${ERROR_MAPPING_USER_LOCKED:OAUTH-AUTH_0004}
            unauthorized: ${ERROR_MAPPING_UNAUTHORIZED:OAUTH-AUTH_0005}