Konfiguracja RestApi

ServiceId

ServiceId to unikalny identyfikator logiczny usługi, wykorzystywany w skryptach, zadaniach skryptowych i modelu danych do odwoływania się do konkretnego endpointu REST. Nie jest to bezpośredni adres URL, lecz alias, który jest mapowany na rzeczywisty adres usługi na podstawie konfiguracji platformy.

Taki sposób korzystania z usług zapewnia elastyczność we wskazywaniu adresów na poszczególnych środowiskach i administratorzy mogą łatwo zmieniać adres na jednym ze środowisk. Przy migracjach bardzo ważne jest, aby po zaktualizowaniu serviceId lub dodaniu nowej usługi informacja o tym znalazła się zarówno w dokumentacji, jak i w zgłoszeniach konfiguracyjnych.

Konfiguracja

Ze względów bezpieczeństwa, namiary na usługi zewnętrzne muszą zostać wskazane w konfiguracji (serviceId).

Konfiguracja ładuje się i przetwarza jednorazowo przy starcie platformy. Oznacza to, że dodatkowe zmiany w namiarach będą wymagały restartu aplikacji (webforms-rest).

Konfiguracja jest czytana z 2 źródeł jednocześnie (dostarczone propertiesy oraz zewnętrzny plik XML). Oba źródła są opcjonalne i nie blokują podniesienia się aplikacji. Jeśli wystąpi konflikt nazw dla serviceId, uwzględniony zostanie ostatni załadowany z listy (kolejność czytania od góry do dołu).

Istnieje możliwość wykorzystania namiaru z definicji konkretnego serviceId w innym. Aby skorzystać z tej opcji, należy zdefiniować pierwszy serviceId, a następnie w namiarze dla drugiego podać nazwę pierwszego serviceId. Np.

scriptservice:
    api:
        - serviceId: "pierwszyServiceId"
          url: "https://moj.namiar"    # namiar: https://moj.namiar
        - serviceId: "drugiServiceId"
          url: "pierwszyServiceId/endpoint"   # namiar: https://moj.namiar/endpoint
          authorization:
            type: basic
            encodedCredentials: cGFzc3dvcmQ=

Skorzystanie z innego namiaru do zdefiniowania nowej konfiguracji działa poprawnie tylko do 1 zagłębienia (zależności: A → B).

Oznacza to, że nie możemy mieć konfiguracji usługi A zależnej od B, która będzie zależna od C (zależności: A → B → C).

Konfiguracja XML

Dla skryptów oraz walidatorów skryptowych:

Plik o nazwie "script-service-api.xml" powinien znajdować się w /etc/eximee/webforms/script-code-config.

Dla handlerów skryptowych:

Plik o nazwie "script-handler-api.xml" powinien znajdować się w /etc/eximee/webforms/script-handler-config.

Plik musi być ręcznie modyfikowany przez administratorów

Struktura pliku:

<?xml version="1.0" encoding="UTF-8" ?>
<scriptservice>
    <api serviceId="mojServiceId"
         url="http://moj.namiar"
         description="Opis dla podpowiedzi w Eximee Designer">
        <authorization type="basic">
            <encodedCredentials>cGFzc3dvcmQ=</encodedCredentials>
        </authorization>
    </api>
    <api serviceId="nbp"
         url="http://api.nbp.pl/api"
         description="Namiar do api udostępnionego przez NBP" />
    <api serviceId="nbpExchange"
         url="nbp/exchangerates"
         description="Namiar na api od NBP dotyczącego kursu walut" />
</scriptservice>

Konfiguracja po załadowaniu:

{
    "nbpExchange": {
        "url": "http://api.nbp.pl/api/exchangerates",
        "description": "Namiar na api od NBP dotyczącego kursu walut"
    },
    "mojServiceId": {
        "url": "http://moj.namiar",
        "description": "Opis dla podpowiedzi w Eximee Designer"
    },
    "nbp": {
        "url": "http://api.nbp.pl/api",
        "description": "Namiar do api udostępnionego przez NBP"
    }
}

Uwierzytelnianie

Basic

Istnieje możliwość zdefiniowana uwierzytelniania typu "Basic" per usługa. Konfiguracji dokonuje się w tym samym pliku, który definiuje namiary na usługę. Przykład przedstawiono powyżej (należy zwrócić uwagę na sekcję "authorization") Zdefiniowanie nagłówka "Authorization" z poziomu serwisu skryptowego (tzw "hardcode") spowoduje wygenerowanie ostrzeżenia w logach. Jeśli w definicji usługi (w pliku) podano sposób uwierzytelnienia ma on priorytet i zastąpi nagłówek "Authorization" będący zaszyty w pliku z serwisem skryptowym.

Wartość w tagu encodedCredentials definiujemy poprzez zabase'owanie wartości

login:hasło

Na przykład jeśli

user='user1'password='password123'

to encodedCredentials przyjmie wartość

<encodedCredentials>dXNlcjE6cGFzc3dvcmQxMjM=</encodedCredentials>

OAuth

Powiązanie konfiguracji API z konfiguracją OAuth

Kolejną dostępną do skonfigurowania metodą jest oAuth (w przepływie server-to-server). Chcąc dodać taką konfigurację do API należy:

• utworzyć konfigurację oAuth o wybranym id

• w elemencie api utworzyć authorization z typem oAuth

• w authorization zdefiniować id konfiguracji

<api ...>
    <authorization type="oAuth">
        <id>idKonfiguracjiOAuth</id>
    </authorization>
</api>
<oAuth id="idKonfiguracjiOAuth" .../>

Parametry konfiguracji OAuth

Na konfigurację oAuth składa się wiele parametrów, z których wszystkie poza authorization i additionalParams ustawiane są jako atrybuty. Będące wyjątkiem authorization i additionalParams definiowane są jako zagnieżdżone elementy. Przykładowo:

<oAuth id="oAuthConfig"
       url="http://localhost:8080/auth/token/"
       grantType="password"
       clientAuthenticationMethod="client_secret_post"
       clientId="yWSvwymlcvB9UoJFvBENscapghxqGy0u"
       clientSecret="jkIWQJM5Iv4mWyQV8RJv28wGRNJq276JttSeCQjkwMDdQpSgqW0YH7NM46pdu7ePGrI9kvuwqC9E76EiMEoOPu5TzdcJEdiX"
       username="admin"
       password="tajnehaslo">
    <authorization type="basic">
        <encodedCredentials>dXNlcjpwYXNzd29yZAo==</encodedCredentials>
    </authorization>
    <additionalParams>
        <language>pl</language>
    <additionalParams>
</oAuth>

Parametr	Wymagany	Opis
id	Tak	Identyfikator konfiguracji oAuth, wskazywany w konfiguracji api.
description	Nie	Opis danej konfiguracji OAuth.
url	Tak	Adres służący do generowania tokenu, np. http://localhost:8080/oauth/token
grantType	Tak	Nazwa wybranego mechanizmu grant type. Obsługiwane wartości parametru: client_credentials - token uzyskiwany na podstawie clientId i clientSecret, password - token uzyskiwany na podstawie dodatkowego username i password
clientAuthenticationMethod	Tak	Nazwa wybranego mechanizmu uwierzytelnienia klienta. Obsługiwane wartości parametru: client_secret_post - dane uwierzytelniające (clientId i clientSecret) w body requestu, client_secret_basic - uwierzytelnienie basiciem (clientId:clientSecret zakodowane base64).
clientId	Tak	Identyfikator klienta
clientSecret	Tak	Sekret ("hasło") klienta
username	Tylko gdy grantType=password	Parametr username wymagany na potrzeby grant type password.
password	Tylko gdy grantType=password	Parametr password wymagany na potrzeby grant type password.
authorization	Nie	Parametr do wykorzystania w przypadku, gdy potrzebne jest zdefiniowanie dodatkowej autoryzacji na potrzeby wygenerowania tokenu. Obecnie wspiera tylko typ basic.
additionalParams	Nie	Parametr pozwalający zdefiniować niestandardowe parametry żądania o wygenerowanie tokenu. Przedstawiona w powyższym przekładzie konfiguracja skutkuje dodaniem jednego parametru language o wartości pl.

Dodatkowe informacje techniczne

Dla autoryzacji OAuth zastosowany jest dodatkowo mechanizm powodujący, że w przypadku uzyskania odpowiedzi ze statusem 401 (Unauthorized) przechowywany obecnie token zostaje unieważniony, a żądanie zostaje jednokrotnie ponowione.