Integraatiotavat

tunnuspalvelu tarjoaa kolme erillistä tapaa integroida sovellus. Ne eivät ole vaihtoehtoisia toisilleen — moni palvelu käyttää useampaa yhdessä (esimerkiksi selainkirjautumista käyttäjille ja M2M-rajapintaa taustatehtäviin).

Integraatiotapa	Käyttötarkoitus	Protokolla
Web-sovelluksen kirjautuminen	Käyttäjä kirjautuu selaimessa sovellukseesi tunnuspalvelun kautta	OpenID Connect, authorization code + PKCE
Mobiili- ja natiivisovellukset	Käyttäjä kirjautuu iOS/Android/työpöytäsovelluksessa	OIDC, public client + PKCE, valinnaisesti DPoP
Machine API (M2M)	Taustapalvelusi kutsuu tunnuspalvelua ohjelmallisesti (käyttäjien luonti, roolit, organisaatiot)	HMAC-SHA256-allekirjoitetut HTTP-pyynnöt
Webhookit	tunnuspalvelu ilmoittaa sovelluksellesi tapahtumista reaaliaikaisesti	HMAC-SHA256-allekirjoitetut HTTP POST -kutsut

tunnuspalvelu ei tue OAuth 2.0:n implisiittistä tai hybridi-flow’ta, eikä dynaamista client-rekisteröintiä (RFC 7591) — kaikki neljä integraatiotapaa edellyttävät, että client on ensin luotu tenantin admin-paneelissa tai machine API:n kautta.

Mitä tarvitset ennen aloitusta

1. Tenant. Jokainen tunnuspalvelu-asiakas saa oman tenantin, jolla on oma isäntänimi (esim. id.esimerkki.fi) ja oma käyttäjäjoukko. Kaikki rajapintakutsut ja kirjautumiset osoitetaan tenantin isäntänimeen.
2. OAuth-client. Client edustaa yhtä sovellusta tenantin sisällä: client_id, sallitut redirect-URIt, sallitut scopet ja grant-tyypit, token-elinajat. Web- ja mobiilisovellukset tarvitsevat oman clientin; M2M-integraatiot tarvitsevat oman clientin, jolle on lisäksi luotu HMAC-avain. Client luodaan tenantin admin-paneelissa (ks. Clientit) tai machine API:n createServiceClient-operaatiolla (ks. Machine API).
3. Redirect-URI (web/mobiili) — täsmällinen URI, johon tunnuspalvelu ohjaa käyttäjän kirjautumisen jälkeen. Rekisteröidään clientille etukäteen; pyynnön redirect_uri-parametrin on täsmättävä merkki merkiltä.

Discovery — lähtöpiste jokaiselle integraatiolle

Jokaisen tenantin OIDC-metadata löytyy vakiopolusta:

GET https://id.esimerkki.fi/.well-known/openid-configuration

Live-esimerkki tuotannosta: https://id.tunnuspalvelu.fi/.well-known/openid-configuration. Kenttien selitykset: Discovery-dokumentti.