Siirry sisältöön
tunnuspalvelu

Mobiili- ja natiivisovellukset

Natiivisovellukset (iOS, Android, työpöytä-CLI) integroituvat samaan authorization code + PKCE -flow’hun kuin web-sovellukset (ks. Web-sovelluksen kirjautuminen), mutta muutamalla erolla: public client, PKCE on aina pakollinen, ja DPoP on suositeltu tokenien sitomiseen laitteeseen. Noudattaa RFC 8252:ta (OAuth 2.0 for Native Apps) ja RFC 9449:ää (DPoP).

1. Public client

Osio nimeltä “1. Public client”

Natiivisovellus ei voi säilyttää client_secret-arvoa turvallisesti, joten se rekisteröidään public-tyyppisenä clienttinä (ei secretiä). Public clientille PKCE on aina pakollinen — token-endpoint todentaa clientin code_verifier:n avulla, ei secretillä. Client luodaan tenantin admin-paneelissa (ks. Clientit) tai machine API:n kautta.

2. Redirect-URI — valitse turvallisin alustasi tukema vaihtoehto

Osio nimeltä “2. Redirect-URI — valitse turvallisin alustasi tukema vaihtoehto”

Kirjautumisen tulos toimitetaan sovellukseen redirect-URIn kautta. Suositusjärjestys:

  1. Vahvistettu https (App Links / Universal Links) — suositeltu. https://app.esimerkki.fi/oauth2redirect, jossa käyttöjärjestelmä on vahvistanut, että domain kuuluu sovelluksellesi (Android assetlinks.json, iOS apple-app-site-association). Toinen sovellus ei voi kaapata sitä, joten tämä on turvallisin vaihtoehto. Tämä on tunnuspalvelun näkökulmasta tavallinen https-redirect — ei erikoista konfigurointia.
  2. Reverse-DNS-muotoinen yksityinen skeema. fi.esimerkki.app:/oauth2redirect. Hyväksytty (RFC 8252 §7.1); turvallinen yhdistettynä PKCE:hen ja täsmälliseen redirect-URI-vertailuun, mutta haitallinen sovellus voi rekisteröidä saman skeeman — käytä siis vaihtoehtoa 1, jos hallinnoit omaa domainia.
  3. Loopback. http://127.0.0.1:<portti>/cb, http://localhost:<portti>/cb tai http://[::1]:<portti>/cb (mikä tahansa portti) — työpöytä-/CLI-sovelluksille.

Paljaita yksisanaisia skeemoja (myapp:) ei hyväksytä.

3. DPoP — laitteeseen sidotut tokenit (RFC 9449)

Osio nimeltä “3. DPoP — laitteeseen sidotut tokenit (RFC 9449)”

DPoP sitoo myönnetyt tokenit sovelluksen hallussa olevaan avainpariin, jolloin varastettu access- tai refresh-token on hyödytön toisella laitteella. Suositellaan vahvasti mobiilille.

  • Sovellus generoi avainparin (ES256) ja lähettää jokaisen /token-pyynnön mukana DPoP:-headerin, joka sisältää allekirjoitetun proof-JWT:n (typ: dpop+jwt, julkinen jwk, htm/htu/iat/jti-claimit).
  • tunnuspalvelu validoi proofin ja leimaa avaimen thumbprintin cnf.jkt-claimiksi access tokeniin; vastauksen token_type muuttuu DPoP:ksi.
  • Refresh token sidotaan samaan avaimeen. Sidottu refresh token voidaan lunastaa vain esittämällä DPoP-proof samalla avaimella — muuten /token palauttaa error=invalid_dpop_proof.
  • Hyväksytyt proof-algoritmit ilmoitetaan /.well-known/openid-configuration → dpop_signing_alg_values_supported. Discovery-dokumentissa arvo on ["ES256"], mutta validaattori hyväksyy käytännössä myös RS256-allekirjoitetut proofit.
  • Proofin iat täytyy olla 60 sekunnin sisällä; jokainen jti on kertakäyttöinen.
  • Myös resurssikutsut vaativat DPoP:n. /userinfo vaatii DPoP-sidotulta access tokenilta Authorization: DPoP <token> -headerin ja proofin, jonka htu/htm täsmäävät pyyntöön, ath täsmää tokeniin ja avain täsmää tokenin cnf.jkt-arvoon. Sidotun tokenin esittäminen pelkkänä Bearer-tokenina, tai ilman proofia, hylätään (401).

Useimmat natiivit OAuth-kirjastot (esim. AppAuth DPoP-laajennuksella) hoitavat proofin generoinnin automaattisesti. Jos refresh token hankittiin DPoP:lla, jokainen myöhempi refresh-kutsu tarvitsee DPoP-proofin samasta avaimesta.

4. Token-elinajat

Osio nimeltä “4. Token-elinajat”

Elinajat ovat client-kohtaisia. Mobiilille on tyypillistä pidempi refresh-token (access token pysyy lyhyenä) — nämä asetetaan clientin luonnin/päivityksen yhteydessä admin-paneelissa tai machine API:n createServiceClient/updateServiceClient-operaatioilla.

5. Refresh-token-rotaatio (aina käytössä)

Osio nimeltä “5. Refresh-token-rotaatio (aina käytössä)”

Jokainen refresh-vaihto rotatoituu: esitetty refresh token kumotaan ja uusi myönnetään samassa perheessä. Kumotun (jo käytetyn) tokenin uudelleenkäyttö tulkitaan varkaudeksi ja kumoaa koko perheen — varastettu refresh token voidaan käyttää korkeintaan kerran ennen kuin varkaus havaitaan ja sessio tapetaan. Tämä koskee kaikkia clienttejä, myös public/mobiili-clienttejä; DPoP:n kanssa se sidotaan lisäksi laitteen avaimeen.

Yhteenveto — suositeltu mobiiliprofiili

Osio nimeltä “Yhteenveto — suositeltu mobiiliprofiili”
Asetus Arvo
Client-tyyppi public (ei secretiä)
PKCE pakollinen (automaattinen public clienteille)
Redirect vahvistettu https App/Universal Link (paras), muuten reverse-DNS-skeema
Tokenit DPoP (cnf.jkt-sidottu), token_type: DPoP
Refresh-elinaika pitkä (esim. 30 vrk)
Rotaatio aina päällä, perhe kumotaan väärinkäytössä

Katso myös

Osio nimeltä “Katso myös”