-
Created by
August Kilponen, last updated on Feb 17, 2022
1 minute read
Sisältö
Rajapintojen kuvaukset
- https://virkailija.opintopolku.fi/kouta-external/swagger/index.html (Swaggerillä voi käyttöliittymän kautta tehdä pyyntöjä palveluun ja tarkastella rajapintojen tietomallia.)
- https://virkailija.opintopolku.fi/kouta-external/redoc/index.html (Redocissa voi tarkastella rajapintojen tietomallia jossa se on paremmin visualisoitu kuin swaggerissä.)
Autentikaatio ja kouta-externalin rajapinnan kutsuminen
Kaikkiin pyyntöhin pitää lisätä Caller-id-tunniste ja osaan pyynnöistä CSRF-suojauksen tarvitsemat tiedot. Tarkemmat ohjeet niistä löytyvät sivun lopusta.
| Vaihe | Esimerkki | Muuta | |
|---|---|---|---|
| 1 | Hae CAS-palvelulta TGT (ticket granting ticket) | Request: POST https://virkailija.opintopolku.fi/cas/v1/tickets HTTP/1.0 Content-type: Application/x-www-form-urlencoded Caller-id: 1.2.246.562.10.00000000001234.kutsuva_palvelu CSRF: CSRF Cookie: CSRF=CSRF; username=username&password=password Response: 201 Created
Location: https://virkailija.opintopolku.fi/cas/v1/tickets/{TGT id}
| Tätä tikettiä käytetään muihin palveluihin tarvittavien CAS-tikettien hakemiseen. Tiketti on voimassa 8 tuntia ja sitä voi uudelleen käyttää sekä tätä että muita palveluita varten eli sitä ei kannata hakea uudestaan jokaisella palveluun tehtävällä pyynnöllä. |
| 2 | Hae CAS-palvelulta ST (service ticket) | Request: POST https://virkailija.opintopolku.fi/cas/v1/tickets/{TGT id} HTTP/1.0
Caller-id: 1.2.246.562.10.00000000001234.kutsuva_palvelu
CSRF: CSRF
Cookie: CSRF=CSRF;
service=https://virkailija.opintopolku.fi/kouta-external/auth/login
Response: 200 OK
{ST id}
| Tätä tikettiä käytetään palveluun autentikoitumiseen. Tiketti on kertakäyttöinen ja se on voimassa 10 sekuntia. |
| 3 | Autentikoidu palveluun ja muodosta sessio | Request: GET https://virkailija.opintopolku.fi/kouta-external/auth/login&ticket={ST id}
Caller-id: 1.2.246.562.10.00000000001234.kutsuva_palvelu
Response: 200 OK
Set-cookie: session={session cookie};Path=/kouta-external;HttpOnly
| Sessio palautuu evästeessä. Se kannattaa ottaa talteen ja käyttää samaa sessiota kaikkiin palveluun tehtäviin pyyntöihin. Sessio on voimassa 1 tunnin ajan. |
| 4 | Kutsu kouta-externalin rajapintaa | Request: GET https://virkailija.opintopolku.fi/kouta-external/hakukohde/1.2.246.562.20.00000000000000001843
Caller-id: 1.2.246.562.10.00000000001234.kutsuva_palvelu
Cookie: session={session cookie};
| Aseta sessio-eväste mukaan pyyntöihin. |
Muita ohjeita
- Opintopolun yleinen autentikaatio-ohje: Koneiden välinen tunnistus ja cas-käyttöönotto
- Opintopolun Caller-id-ohje: Kutsujan tunnisteen (caller-id) lisääminen rajapintakutsuihin
- Opintopolun CSRF-ohje: CSRF-tokenin lisääminen HTTP-kutsuihin