Przejdź do treści

Klient OAuth 2.0 Client Credentials

Ta strona jest dla programistów backendu, którzy wywołują zewnętrzne API chronione tokenem OAuth 2.0 w przepływie Client Credentials. Opisuje pakiet logintegra.oauth, klienta MOWI OTM oraz sposób dodania kolejnego klienta.

Jak to działa

Wywołujący dostaje gotowy RestTemplate. Nie widzi tokenu i nie dołącza go ręcznie. Token pobiera i odświeża Spring Security OAuth2 Client w wersji zarządzanej przez Spring Boot 2.7.

Klasa Zadanie
OAuthClientCredentialsProperties konfiguracja jednego klienta: registrationId, tokenUrl, clientId, clientSecret, scope, timeouty
ClientCredentialsTokenProvider pobiera token z tokenUrl, trzyma go w pamięci i pobiera nowy po wygaśnięciu
OAuthAuthorizationInterceptor dołącza nagłówek Authorization: Bearer, a po odpowiedzi 401 ponawia wywołanie z nowym tokenem
OAuthRestTemplateFactory składa powyższe w jeden RestTemplate
OAuthTokenErrorTranslator zamienia błędy pobierania tokenu na OAuthTokenException i loguje je bez sekretów
MowiOtmClientService klient API MOWI OTM, metoda sendStatus wysyła POST na /status2otm
OAuthTokenException błąd pobrania tokenu z podaniem przyczyny

Zasady działania:

  1. Token żyje w pamięci jednej instancji aplikacji i nie przeżywa jej restartu.
  2. Kolejne wywołania używają tego samego tokenu aż do jego wygaśnięcia.
  3. Gdy tokenu brakuje albo wygasł, następne wywołanie pobiera nowy.
  4. Każdy klient ma własny magazyn tokenów, więc klienci nie współdzielą tokenów.
  5. Nie ma zadania cyklicznego, bo token pobiera się na żądanie.
sequenceDiagram
    participant K as Kod wywołujący
    participant R as RestTemplate
    participant A as Serwer autoryzacji
    participant S as Serwis docelowy
    K->>R: postForEntity
    R->>A: pobranie tokenu, gdy brak w pamięci
    A-->>R: access_token
    R->>S: żądanie z Bearer
    S-->>R: 401
    R->>A: nowy token
    A-->>R: access_token
    R->>S: to samo żądanie z nowym tokenem
    S-->>R: 200
    R-->>K: odpowiedź

Po drugiej odpowiedzi 401 wywołujący dostaje HttpClientErrorException.Unauthorized. Ponowienie następuje tylko raz.

Błędy pobrania tokenu

Gdy token nie da się pobrać, RestTemplate rzuca OAuthTokenException. Pole reason mówi, co zawiodło. Nieudany wynik nie jest zapamiętywany, więc kolejne wywołanie próbuje ponownie bez restartu aplikacji.

reason Kiedy
NOT_CONFIGURED klient jest wyłączony albo bez konfiguracji
INVALID_CREDENTIALS serwer autoryzacji odrzucił clientId lub clientSecret, np. błąd invalid_client albo status 401
SERVER_UNAVAILABLE timeout, błąd sieci, status 5xx albo niepoprawna odpowiedź
UNKNOWN pozostałe przypadki

W logach pojawia się przyczyna, kod błędu OAuth i status HTTP. Sekret klienta, token i treść odpowiedzi serwera nie są logowane.

Konfiguracja MOWI OTM

Klucze leżą pod prefiksem mowi.otm.oauth. Wartości trafiają do konfiguracji środowiska, nigdy do repozytorium. Dane dostępowe są w Zoho Vault we wpisie "MOWI OTM Autoryzacja OAuth 2.0".

mowi:
  otm:
    oauth:
      enabled: 'true'
      tokenUrl: '<VAULT>'
      clientId: '<VAULT>'
      clientSecret: '<VAULT>'
Klucz Domyślnie Znaczenie
enabled false włącza klienta
tokenUrl puste adres serwera autoryzacji
clientId puste identyfikator klienta
clientSecret puste sekret klienta
scope puste zakresy rozdzielone spacją, opcjonalne
clientAuthentication basic basic wysyła dane w nagłówku, post w treści żądania
connectTimeoutMs 5000 timeout połączenia
readTimeoutMs 10000 timeout odczytu

Włączony klient bez tokenUrl, clientId lub clientSecret kończy start aplikacji błędem. Timeouty dotyczą zarówno pobierania tokenu, jak i wywołań serwisu docelowego.

Użycie

Do wysyłki statusów do MOWI OTM służy MowiOtmClientService. Używa on beana mowiOtmRestTemplate, więc kod wywołujący nie zajmuje się tokenem. Adres API MOWI ustawia klucz mowi.otm.baseUrl, bez końcówki /status2otm.

@Autowired
MowiOtmClientService mowiOtmClientService

void notifyArrival(Long transportId) {
    try {
        mowiOtmClientService.sendStatus([transportId: transportId, status: 'ARRIVAL'])
    } catch (OAuthTokenException e) {
        // Nie udało się pobrać tokenu, e.reason mówi dlaczego.
        log.warn "Nie wysłano statusu do MOWI OTM: ${e.message}"
        throw e
    } catch (HttpStatusCodeException e) {
        // MOWI odpowiedziało błędem, także 401 po ponowieniu z nowym tokenem.
        log.warn "MOWI OTM odpowiedział statusem ${e.rawStatusCode}"
        throw e
    }
}

Pola statusu w przykładzie są poglądowe. Treść żądania jest przekazywana jako JSON bez zmian. Produkcyjną wysyłkę statusów po potwierdzeniu i wycofaniu statusu obsługuje MowiOtmStatusService, opisany w MOWI OTM – wysyłka statusów transportu.

Wywołanie nie przechodzi przez HttpService. Logowanie i ponawianie z HttpService trzeba w razie potrzeby dodać w kodzie wywołującym.

Dodanie kolejnego klienta

Każdy klient potrzebuje własnej konfiguracji i jednego beana.

  1. Dodaj komponent z @Value, wzorowany na MowiOtmOAuthConfig, z własnym prefiksem kluczy i unikalnym registrationId.
  2. Dodaj metodę toProperties(), która zwraca OAuthClientCredentialsProperties.
  3. Zdefiniuj bean w klasie @Configuration.
@Configuration
class PartnerRestTemplateConfiguration {

    @Bean
    RestTemplate partnerRestTemplate(PartnerOAuthConfig config) {
        OAuthRestTemplateFactory.create(config.toProperties())
    }
}

Domyślna klasyfikacja błędów pasuje do serwerów zgodnych z RFC 6749. Gdy serwer partnera zachowuje się inaczej, przekaż podklasę OAuthTokenErrorTranslator jako drugi argument OAuthRestTemplateFactory.create.

Dwa beany tego samego typu RestTemplate wymagają wstrzykiwania po nazwie albo przez @Qualifier. Wstrzyknięcie samego typu RestTemplate byłoby niejednoznaczne.

Ograniczenia

Ograniczenie Skutek
Spring Security 5.7 nie ma interceptora OAuth2 dla RestTemplate własny OAuthAuthorizationInterceptor, do usunięcia po przejściu na Spring Security 6.4 i nowsze
token jest w pamięci instancji po restarcie albo w drugiej instancji pobierany jest nowy token
klienci są zdefiniowani w kodzie nowy klient wymaga zmiany kodu, a nie samej konfiguracji

Testy klienta leżą w ClientCredentialsTokenProviderSpec i działają na lokalnym serwerze HTTP, bez dostępu do sieci.

Ostatnia zmiana: 2026-11-13 · kamil_szulc
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e