1.6.6. OTP Verification Provider#

OTP (One-Time Password) Verification Provider, Keysis altyapısı üzerinden tek kullanımlık doğrulama kodu üretimi ve doğrulaması hizmeti sunar. Üretilen kodlar e-posta veya SMS kanalları üzerinden kullanıcıya iletilir; doğrulama işlemi referans kimliği ile gerçekleştirilir.

Kodlar Redis üzerinde TTL ile saklanır, belirli deneme sayısını aştığında otomatik olarak geçersiz kılınır.

Genel Akış#

sequenceDiagram
    participant İstemci as İstemci Uygulama
    participant Keysis as Keysis OTP Servisi
    participant Redis as Redis Cache
    participant Kafka as Kafka Notification

    İstemci->>Keysis: POST /otp/generate
    Keysis->>Keysis: Kod üretimi (SecureRandom)
    Keysis->>Redis: Kod + referenceId kaydet (TTL)
    Keysis->>Kafka: Bildirim gönder (MAIL/SMS)
    Keysis-->>İstemci: referenceId, maskedReceiver, expirationDate

    Note over İstemci: Kullanıcı kodu alır (e-posta/SMS)

    İstemci->>Keysis: POST /otp/verify (referenceId + code)
    Keysis->>Redis: referenceId ile kod sorgula
    Keysis->>Keysis: Kod karşılaştır
    Keysis-->>İstemci: true / false

İstemci Bağımlılığı#

OTP servisini Feign Client üzerinden kullanabilmek için projenize aşağıdaki bağımlılığı eklemeniz gerekmektedir.

Gradle Bağımlılıkları

dependencyManagement {
    imports {
        mavenBom "tr.com.havelsan.framework.system:hvl-oauth-parent"
    }
}

compile (
    [group: 'tr.com.havelsan.framework.oauth.cloud' , name: 'hvl-oauth-authz-cloud-client']
)

Feign Client Aktivasyonu#

Feign client uçlarını kullanabilmek için configuration bean'ine aşağıdaki annotation eklenmelidir.

• @HvlEnableAuthzCloudClient

Rest Servis Tanımı#

OTP servisi HvlAuthzOtpRestService Feign Client arayüzü üzerinden iki adet uç sunmaktadır.

Servis Kullanımı

@Service
@RequiredArgsConstructor
public class MyOtpService {

    private final HvlAuthzOtpRestService hvlAuthzOtpRestService;

    public HvlOAuthOtpGenerationResponseModel generateOtp(HvlOAuthOtpChannel channel, String receiver) {
        HvlOAuthOtpGenerationRequestModel request = new HvlOAuthOtpGenerationRequestModel();
        request.setChannel(channel);
        request.setReceiver(receiver);
        HvlResponse<HvlOAuthOtpGenerationResponseModel> response = hvlAuthzOtpRestService.generate(request);
        return response.getData();
    }

    public boolean verifyOtp(String referenceId, String code) {
        HvlOAuthOtpVerificationRequestModel request = new HvlOAuthOtpVerificationRequestModel();
        request.setReferenceId(referenceId);
        request.setCode(code);
        HvlResponse<Boolean> response = hvlAuthzOtpRestService.verify(request);
        return response.getData();
    }
}

@Validated
@HvlPublicFeignRestService
@FeignClient(name = "${hvl.oauth.authz.otp.service.name:otpRestService}",
             path = "${hvl.oauth.authz.otp.service.path:/otp}",
             url = "${hvl.oauth.authz.otp.service.url:${hvl.oauth.authz.service.url}}")
public interface HvlAuthzOtpRestService {

    @PostMapping(value = "/generate",
                 consumes = MediaType.APPLICATION_JSON_VALUE,
                 produces = MediaType.APPLICATION_JSON_VALUE)
    HvlResponse<HvlOAuthOtpGenerationResponseModel> generate(
            @NotNull @Valid @RequestBody HvlOAuthOtpGenerationRequestModel otpGenerationRequestModel);

    @PostMapping(value = "/verify",
                 consumes = MediaType.APPLICATION_JSON_VALUE,
                 produces = MediaType.APPLICATION_JSON_VALUE)
    HvlResponse<Boolean> verify(
            @NotNull @Valid @RequestBody HvlOAuthOtpVerificationRequestModel otpVerificationRequestModel);
}

REST API Uçları#

POST /otp/generate#

Tek kullanımlık doğrulama kodu üretir ve belirtilen kanal (MAIL veya SMS) üzerinden alıcıya iletir.

İstek Modeli — HvlOAuthOtpGenerationRequestModel#

Örnek İstek:

{
  "channel": "MAIL",
  "receiver": "kullanici@example.com",
  "language": "tr"
}

Yanıt Modeli — HvlOAuthOtpGenerationResponseModel#

Örnek Yanıt:

{
  "data": {
    "referenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "channel": "MAIL",
    "maskedReceiver": "***ci@example.com",
    "expirationMinutesTtl": 3,
    "expirationDate": "2026-09-10T15:40:00+03:00"
  },
  "errors": null,
  "warnings": null
}

POST /otp/verify#

Üretilmiş OTP kodunu referans kimliği ile doğrular.

İstek Modeli — HvlOAuthOtpVerificationRequestModel#

Örnek İstek:

{
  "referenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "code": "482916"
}

Yanıt Modeli — HvlResponse<Boolean>#

Örnek Yanıt (Başarılı):

{
  "data": true,
  "errors": null,
  "warnings": null
}

Kanal Tipleri — HvlOAuthOtpChannel#

Hata Kodları#

Doğrulama sırasında aşağıdaki hata durumları oluşabilir:

Yapılandırma Parametreleri#

OTP servisinin sunucu tarafı yapılandırması aşağıdaki parametreler ile kontrol edilir:

İstemci Tarafı Yapılandırması#

İstemci uygulamanın application.yml dosyasında Feign Client bağlantı ayarları:

hvl:
  oauth:
    authz:
      service:
        url: http://localhost:9190
      otp:
        service:
          name: otpRestService
          path: /otp
          url: ${hvl.oauth.authz.service.url}

Ön Koşullar#

OTP servisinin düzgün çalışabilmesi için aşağıdaki altyapı bileşenlerinin hazır olması gerekmektedir:

1. Redis: OTP kodları Redis üzerinde TTL ile saklanır. Redis bağlantısı yapılandırılmış olmalıdır.
2. Kafka: OTP kodları Mail veya SMS bildirim kanallarına Kafka üzerinden iletilir. İlgili topic'lerin oluşturulmuş olması gerekmektedir.
3. Bildirim Servisi: Mail veya SMS kanalını dinleyen bir bildirim servisi (Notification) çalışır durumda olmalıdır.
4. Keysis Authorization Servisi: OTP uçları Keysis authorization servisi (hvl-oauth-authz-starter) üzerinden sunulmaktadır.