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:
- Token żyje w pamięci jednej instancji aplikacji i nie przeżywa jej restartu.
- Kolejne wywołania używają tego samego tokenu aż do jego wygaśnięcia.
- Gdy tokenu brakuje albo wygasł, następne wywołanie pobiera nowy.
- Każdy klient ma własny magazyn tokenów, więc klienci nie współdzielą tokenów.
- 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".
| 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.
- Dodaj komponent z
@Value, wzorowany naMowiOtmOAuthConfig, z własnym prefiksem kluczy i unikalnymregistrationId. - Dodaj metodę
toProperties(), która zwracaOAuthClientCredentialsProperties. - 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