# 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](<https://docs.logintegra.com/apollo-backend/7. Microservices %26 Integrations/integrations/mowi-otm/index.md>).

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.
