Skip to content

Commit

Permalink
AUT-1529 Move ID token signing key process information to separate ch…
Browse files Browse the repository at this point in the history
…apter

Co-authored-by: Alar Kvell <[email protected]>
  • Loading branch information
naare and alarkvell committed Nov 22, 2023
1 parent c091c70 commit 7b543da
Show file tree
Hide file tree
Showing 3 changed files with 91 additions and 17 deletions.
50 changes: 41 additions & 9 deletions TechnicalSpecification.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ permalink: TechnicalSpecification

# Technical specification
{: .no_toc}
v 1.16, 26.10.2023
v 1.17, 23.11.2023

- TOC
{:toc}
Expand Down Expand Up @@ -524,27 +524,25 @@ The identity token is signed by the TARA authentication service. The signature m

TARA uses the `RS256` signature algorithm. The client application must, at least, be able to verify the signature given by using this algorithm. It would be reasonable to use a standard JWT library which supports all JWT algorithms. The change of algorithm is considered unlikely, but possible in case a security vulnerability is detected in the `RS256`.

For the signature verification the public signature key of TARA must be used. The public signature key is published at the public signature key endpoint (see chapter 6 "Endpoints").
For the signature verification, the public signature key of TARA must be used. The public signature key is published at the public signature key [endpoint](#7-endpoints-and-timeouts).

The public signature key is stable - the public signature key will be changed according to security recommendations. However, the key can be changed without prior notice for security reasons. Key exchange is carried out based on [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys) standard.
The public signature key is stable - the public signature key will be changed according to security recommendations. However, the key can be changed without prior notice for security reasons. The key change process is described in a separate [chapter](#54-id-token-signing-key-change).

The public signature key has an identifier (`kid`). The key identifier is aligned with the best practices of [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#Signing) and OAuth 2.0 that enables the key exchange without the service interruption.

In case of the signing key change, two keys will be published at the public signature key endpoint, both will have unique `kid` identifiers.

TARA issues `kid` field in the response of the request of identity token (JWT header element `kid`). `kid` refers to the key that the client application has to use for the verification of a signature.

We recommend to buffer the signature key (together with `kid` value) in order to decrease the amount of requests made to TARA server. However, it is allowed to request the key on each validation.

For signature validation following checks needs to be performed on client application:
**For signature validation the following checks need to be performed on the client application:**

1 - Read the `kid` value from the JWT header.

2.1 - If the client application does not buffer the public key, make request to public signature key endpoint and select key corresponding to `kid` value received from JWT header.
2.1 - If the client application does not buffer the public key, make a request to the public signature key endpoint and select the key corresponding to the `kid` value received from the JWT header.

2.2 - If client application buffers the public key (it needs to be buffered together with `kid` value), it needs to compare the `kid` value from JWT header with buffered `kid` value. If they match, buffered key can be used. If not client application needs to make request to public signature key endpoint and select key corresponding to `kid` value received from JWT header and buffer it.
2.2 - If the client application buffers the public key (it needs to be buffered together with the `kid` value), it needs to compare the `kid` value from the JWT header with the buffered `kid` value. If they match, the buffered key can be used. If not, the client application needs to make a request to the public signature key endpoint and select the key corresponding to the `kid` value received from the JWT header and buffer it together with the corresponding `kid` value. Alternatively, the client application can buffer all the published keys from the public signature key endpoint together with `kid` values and during validation select the matching key from the buffer. However, in that case, the buffer should have an expiration time. Recommended buffer expiration should be between 5 minutes to 24 hours.

3 - Validate the signature using the key corresponding to `kid` value from the JWT header.
3 - Validate the signature using the key corresponding to the `kid` value from the JWT header.

NB! "Hardcoding" the key to client application configuration must be avoided. The key change will be typically communicated (except of urgent security reasons), but manual key handling will result downtime in client application for the period when TARA is already using the new key until the new key is taken use in client application.

Expand Down Expand Up @@ -646,6 +644,40 @@ Further information: unfortunately, this topic is not presented clearly in the O

Logging must enable the reconstruction of the course of the communication between TARA and the client application for each occasion of using TARA. For this purpose, all requests and responses must be logged by TARA as well as by the client application: [authentication request](#41-authentication-request), [redirect request](#42-redirect-request) and [identity token request](#43-identity-token-request). As the volumes of data transferred are not large, the URL as well as the identity token must be logged in full. The retention periods of the logs should be determined based on the importance of the client application. We advise using 1 … 7 years. In case of any issue, please submit an excerpt from the log (Which requests were sent to TARA? Which responses were received?).

### 5.4 ID token signing key change

The key change is carried out based on [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys) standard.

RIA notifies contact persons of integrators by e-mail about identity token signing key change.

Until the notified date, TARA signs identity tokens with the key that is being used until then. From the notified date, TARA will start signing identity tokens with the new key, which will be added to [public signature key endpoint](#7-endpoints-and-timeouts) by the time the first identity token is signed with it. Therefore, for some time, two public keys are visible at the public signature key endpoint at the same time, each with its own unique `kid` identifier. Example of publishing two keys:
```json
{
"keys": [
{
"use": "sig",
"kty": "RSA",
"kid": "8b2c7561-fdf8-41d4-b466-ab323c3865c6",
"alg": "RS256",
"n": "sqEw...",
"e": "AQAB"
},
{
"use": "sig",
"kty": "RSA",
"kid": "1c5b7961-41d4-b468-a768-db523c3617f4",
"alg": "RS256",
"n": "y7XY...",
"e": "AQAB"
}
]
}
```

The old public key will be removed from the public signature key endpoint after the last identity tokens signed with it have expired.

See also [Verifying the signature](#511-verifying-the-signature) chapter for information on how the public key must be used in signature validation.

## 6 eIDAS levels of assurance

As stated by [eIDAS regulation](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32014R0910&from=EN), eIDAS level of assurance (LoA) is the level of reliability (high, substantial, low) assigned to a means of authentication under the implementing regulation [(EL) 2015/1502](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32015R1502&from=EN). The LoA of a means of authentication is determined by several aspects: the basis of identity issuance, organizational processes, the technical solution and management of the solution.
Expand Down
49 changes: 41 additions & 8 deletions TehnilineKirjeldus.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ permalink: TehnilineKirjeldus

# Tehniline kirjeldus
{: .no_toc}
v 1.25, 26.10.2023
v 1.26, 23.11.2023

- TOC
{:toc}
Expand Down Expand Up @@ -523,14 +523,12 @@ Identsustõend väljastatakse autentimisteenuse TARA poolt allkirjastatult. Allk

Allkirjaalgoritmina kasutab TARA `RS256`. Klientrakendus peab suutma vähemalt selle algoritmiga antud allkirja kontrollida. Allkirja kontrollimine on otstarbekas teostada standardse JWT teegiga, mis toetaks kõiki JWT algoritme. Seda vähetõenäoliseks, kuid siiski võimalikuks juhuks, kui `RS256`-s peaks avastatama turvanõrkus, mis tingib algoritmi vahetamise.

Allkirja kontrollimisel tuleb kasutada TARA avalikku allkirjavõtit (edaspidi "võti"). Võtme saate võtmeväljastuse otspunktist (vt allpool jaotis "Otspunktid").
Allkirja kontrollimisel tuleb kasutada TARA avalikku allkirjavõtit (edaspidi "võti"). Võtme saate võtmeväljastuse [otspunktist](#6-otspunktid-ja-aegumisajad).

Võti on tüüpiliselt stabiilne. Vahetame võtit vastavalt turvasoovitustele, kuid ei ole välistatud erakorraline võtmevahetus võtme korrumpeerumise korral. Võtmevahetuse protsessis järgime [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys) standardit.
Võti on tüüpiliselt stabiilne. Vahetame võtit vastavalt turvasoovitustele, kuid ei ole välistatud erakorraline võtmevahetus võtme korrumpeerumise korral. Võtmevahetuse protsess on kirjeldatud [eraldi peatükis](#54-identsust%C3%B5endi-allkirjastamise-v%C3%B5tme-vahetus).

Võtmel on identifikaator (`kid`). Võtmeidentifikaatorite osas järgime [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#Signing) ja OAuth 2.0 soovitatud praktikat, mis teeb võimalikuks võtmevahetuse ilma teenuse katkestuseta.

Võtmevahetusel on lühikese perioodi jooksul võtmeväljastuse otspunktist nähtavad kaks võtit, kumbki oma identifikaatoriga.

Identsustõendi päringu vastuses väljastab TARA klientrakendusele ka `kid` (JWT päise (_header_) element `kid`). See `kid` osutab võtmele, mida peate väljastatud tõendi allkirja kontrollimisel kasutama.

Soovitame võtit puhverdada (koos `kid` väärtusega), kuna see vähendab TARA serveri poole tehtavate päringute arvu. Kuid aktsepteeritav on ka võtme pärimine igas autentimises.
Expand All @@ -539,9 +537,9 @@ Soovitame võtit puhverdada (koos `kid` väärtusega), kuna see vähendab TARA s

1 - JWT päisest lugema element `kid` väärtuse.

2.1 - Juhul kui võtit ei puhverdata teostama päringu võtmeväljastuse otspunktile ning võtma JWT päisest saadud `kid` väärtusele vastava võtme.
2.1 - Juhul kui võtit ei puhverdata, teostama päringu võtmeväljastuse otspunktile ning võtma JWT päisest saadud `kid` väärtusele vastava võtme.

2.2 - Võtme puhverdamisel tuleb seda teha koos `kid` väärtusega. Valideerimisel võrrelda vastusest saadud `kid` väärtust puhverdatud võtme `kid` väärtusega. Juhul kui väärtused kattuvad kasutada puhverdatud võtit. Mittekattumise korral tuleb teostada päring võtmeväljastuse otspunktile ning võtta JWT päisest saadud `kid` väärtusele vastav võti ning puhverdada.
2.2 - Võtme puhverdamisel tuleb seda teha koos `kid` väärtusega. Valideerimisel võrrelda vastusest saadud `kid` väärtust puhverdatud võtme `kid` väärtusega. Juhul kui väärtused kattuvad kasutada puhverdatud võtit. Mittekattumise korral tuleb teostada päring võtmeväljastuse otspunktile ning võtta JWT päisest saadud `kid` väärtusele vastav võti ning puhverdada see koos vastava `kid` väärtusega. Alternatiivina võib puhverdada võtmeväljastuse otspunktist kõik võtmed koos `kid` väärtustega ning valideerimisel kasutada puhvrist sobivat võtit. Sellisel juhul peaks puhver olema aeguv. Soovitav puhvri eluiga peaks jääma vahemikku 5 minutit kuni 24 tundi.

3 - Teostama allkirja kontrolli JWT päises oleva `kid` väärtusele vastava võtmega.

Expand Down Expand Up @@ -651,7 +649,41 @@ Soovi korral võite veel tutvuda ründe (ja kaitse) detailse seletusega: [Võlts
### 5.3 Logimine

Logimine peab võimaldama rekonstrueerida TARA ja klientrakenduse suhtluse käigu TARA iga kasutuse jaoks. Selleks tuleb nii TARA kui ka klientrakenduse poolel logida kõik päringud ja päringute vastused: [autentimispäring](#41-autentimisp%C3%A4ring), [tagasisuunamispäring](#42-tagasisuunamisp%C3%A4ring) ja [identsustõendipäring](#43-identsust%C3%B5endip%C3%A4ring). Kuna edastatavad andmemahud ei ole suured, siis tuleb logida nii URL kui ka identsustõend täielikul kujul. Logide säilitamistähtaja määramisel arvestada klientrakenduse olulisust. Orientiiriks pakume 1..7 aastat. Probleemide lahendamiseks pöördumisel palume esitada väljavõte logist (mis päringud TARA poole saadeti? mis saadi vastuseks?).


### 5.4 Identsustõendi allkirjastamise võtme vahetus

Võtmevahetuse protsessis järgitakse [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys) standardit.

RIA teavitab identsustõendi allkirjastamise võtme vahetamisest liidestujate kontaktisikuid e-kirjaga.

Kuni teavitatava kuupäevani allkirjastab TARA identsustõendeid seni kasutusel oleva võtmega. Alates teavitatavast kuupäevast hakkab TARA allkirjastama identsustõendeid uue võtmega, mis lisatakse [võtmeväljastuse otspunkti](#6-otspunktid-ja-aegumisajad) hiljemalt sellega esimese identsustõendi allkirjastamise ajaks. Seega on teatud ajaperioodil võtmeväljastuse otspunktis nähtavad kaks avalikku võtit korraga, kumbki oma unikaalse `kid` identifikaatoriga. Näide kahe võtme publitseerimisest:
```json
{
"keys": [
{
"use": "sig",
"kty": "RSA",
"kid": "8b2c7561-fdf8-41d4-b466-ab323c3865c6",
"alg": "RS256",
"n": "sqEw...",
"e": "AQAB"
},
{
"use": "sig",
"kty": "RSA",
"kid": "1c5b7961-41d4-b468-a768-db523c3617f4",
"alg": "RS256",
"n": "y7XY...",
"e": "AQAB"
}
]
}
```

Vana avalik võti eemaldatakse võtmeväljastuse otspunktist pärast seda kui sellega allkirjastatud viimased identsustõendid on aegunud.

Vaata ka peatükki [Allkirjade kontrollimine](#511-allkirja-kontrollimine), kus kirjeldatakse, kuidas peab avalikku võtit allkirja kontrollimiseks kasutama.

## 6 Otspunktid ja aegumisajad

6.1 Testteenus
Expand Down Expand Up @@ -765,6 +797,7 @@ NB! Riigi Infosüsteemi Amet ei taga teiste riikide autentimisteenuste toimimist

| Versioon, kuupäev | Muudatus |
|-----------------|--------------|
| 1.26, 23.11.2023 | TARA võtmevahetusprotsess viidud eraldi peatükki. |
| 1.25, 26.10.2023 | TLS usaldusankru muutus (juursertifikaadi vahetus, lõppolemi sertifikaadi vahetus). Täpsustatud TLS usaldusankru määramise ja sertifikaatide tühistamise kontrollimise juhiseid. |
| 1.24, 09.05.2023 | Formaadi ja kirjavigade parandused. Autentimisvahendite nimetuste ühtlustamine, EU eID kui autentimismeetod (piiriülene autentimine eIDAS taristus). |
| 1.23, 28.04.2023 | Täpsustatud eidas:country:xx skoobi kasutuse kirjeldust. |
Expand Down
9 changes: 9 additions & 0 deletions Uudised.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ permalink: Uudised

# Uudised

**23.11.2023**
## TARA identsustõendi allkirjastamise võtme vahetus
TARA toodangukeskkonnas on alates 01.08.2023 lisatud https://tara.ria.ee/oidc/jwks nimekirja praegu kasutatava võtme (`kid` väärtusega `public:SOP0AEUxG6ZgUzYH`) kõrvale uus avalik võti (`kid` väärtusega `fcd76c92-bc34-4e9f-b874-4c816c34639d`).
Tehnilises kirjelduses on täpsustatud peatükke [Allkirja kontrollimine](TehnilineKirjeldus#511-allkirja-kontrollimine) ja [Identsustõendi allkirjastamise võtme vahetus](TehnilineKirjeldus#54-identsust%C3%B5endi-allkirjastamise-v%C3%B5tme-vahetus).

Uue võtme kasutusele võtu kuupäev teavitatakse eraldi. Kuni teavitatava kuupäevani allkirjastab TARA identsustõendeid praegu kasutatava võtmega (`kid` väärtusega `public:SOP0AEUxG6ZgUzYH`). Alates teavitatavast kuupäevast hakkab TARA allkirjastama identsustõendeid uue võtmega (`kid` väärtusega `fcd76c92-bc34-4e9f-b874-4c816c34639d`) ja vana võti eemaldatakse võtmeväljastuse otspunktist.

___

**26.10.2023**
## 07.11.2023 vahetub TLS sertifikaat `tara-test.ria.ee` keskkonnas ja 14.11.2023 vahetub `tara.ria.ee` keskkonnas.
• Palume klientidel, kes on oma teenuses usaldanud senist DigiCert juursertifikaati (DigiCert Global Root CA), lisada enne vahetusaega usaldusankruks uus DigiCert juursertifikaat ([DigiCert Global Root G2](https://cacerts.digicert.com/DigiCertGlobalRootG2.crt.pem)) ja eemaldada pärast vahetusaega senine juursertifikaat.<br/>
Expand Down

0 comments on commit 7b543da

Please sign in to comment.