Katson sulautus

Johdanto

Katson sulautuksella (KaSu) tarkoitetaan Katso-palvelun liittämistä väliaikaisesti Suomi.fi-valtuuksiin. Asiointipalvelusta Suomi.fi-valtuuksiin tehtävissä valtuustarkistuskyselyissä voidaan perusrekistereiden ja valtuusrekisterin lisäksi hyödyntää myös Katso-palveluun määriteltyjä Katso-rooleja.Sulautusta tarvitaan, jos asiointipalvelun loppukäyttäjinä on organisaatioita, joiden Y-tunnus ja/tai edustamisoikeudellinen henkilö ei ole kaupparekisterissä tai YTJ:ssä. Tällaisia organisaatioita ovat esimerkiksi kunnat, seurakunnat, oppilaitokset, yhdistykset, säätiöt, elinkeinoyhtymät, kuolinpesät, ja julkiset viranomaiset.

Katson sulautuksen edellytykset

  • asiointipalvelussa ei ole ulkomaalaisia loppuasiakkaita
  • loppuasiakkaina on organisaatioita, joista ei löydy edustajatietoa perusrekistereistä

KaSu-toiminnallisuuden kuvaus

Valtuuskyselyssä asiointipalvelulle ei palauteta Katso-rooleja, vaikka henkilölle sellainen löytyisikin Katso-palvelusta. Kyselyssä palautetaan Katso-roolia vastaava valtuuskoodin tekninen tunniste (URI). Valtuuskyselyssä palautetaan siis aina valtuuskoodi riippumatta siitä, onko valtuus Suomi.fi-valtuuksissa vai Katso-palvelussa Katso-roolina.

Kun KaSu-ominaisuus on käytössä, tehdään tarkistukset näin:

  1. Tarkistetaan henkilön asiointikelpoisuus Väestötietojärjestelmästä
  2. Tarkistetaan asiointioikeus valittujen sääntömoottorin sääntöjen perusteella kaupparekisteristä ja yritystietojärjestelmästä (toimielinroolit, nimenkirjoitusoikeus)
  3. Tarkistetaan henkilön Katso-roolit Katso-palvelusta

KaSu-toiminnallisuuden käyttöönotto

Jos asiointipalvelussa on tarve KaSu-ominaisuudelle, toimi näin:

  1. Ota käyttöön Suomi.fi-tunnistus: https://palveluhallinta.suomi.fi/fi/sivut/tunnistus/esittely
  2. Ota käyttöön Suomi.fi-valtuudet täyttämällä liittymisilmoitus: https://esuomi.fi/palveluntarjoajille/valtuudet/kayttoonotto/
  3. Määrittele asiointivaltuudet (valtuuskoodit): https://esuomi.fi/palveluntarjoajille/valtuudet/valtuuskoodien-maaritysohje/
  4. Määrittele mitkä Katso-roolit liitetään mihinkin valtuuskoodiin ja toimita ehdotus Suomi.fi-valtuuksien käyttöönottotiimille
  5. Lisää Katso-liityntäagentin metadataan julkinen avain (ohje alla). Tuotantoympäristössä hyödyntäjäorganisaatio tilaa metadatan muutoksen CGI:ltä: support.katve.fi (a) cgi.com
  6. Toimita käyttöönottotiimille Katso-liityntäagentin tunniste (entity id)

Tämän jälkeen käyttöönottotiimi voi tehdä Katso-roolien liitokset valtuuskoodeihin sekä lisätä liityntäagentin tunnisteen palvelun konfiguraatioon ja Katso-roolien tarkistaminen Suomi.fi-valtuuksien kautta on mahdollista. Valtuuskoodiin liitetään hyödyntäjäorganisaation määrittelemän Katso-roolin lisäksi aina myös ”all” ja ”secondady_admin” -roolit ellei toisin haluta.

Valtuuskoodiin liitetyt Katso-roolit tulevat näkyviin sääntömoottorin hallintakäyttöliittymälle säännön 019.003.1.2 yhteyteen:

Katso-liityntäagentin konfigurointi

Liityntäagentin metadataan lisätään uusi KeyDescriptor -elementti olemassa olevan elementin lisäksi. Tämä sijoitetaan metadatassa ensimmäiseksi avaimeksi.

Liityntäagentin julkinen avain testiympäristöön

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAoSqmJD/0n1lhAhOaOtirewDBfPptNCD/J9/ayORlH24Lg0LFZWoBdrFmQY1+KgOft5g6lLMuV/NqcIdHRqbY2XEoRXgJzmzvWa9gCVQTb73XP8wAgZc5EO6iGZa/WjE2qZUtgiI9eq/PzmduC5UH9+B0GUM37nGhdrgNP9HwZ/W50Lj3QLqBO1/NWDaY0j7RTAVNda1CsrjReHwOkoIaM8dy9NTq347KMFdQDEQeLmXkojKCh7wIee358492UDosk9BL4dyGcbFZgL0KNMmbcT6tld53EkVqNsHK/iBMFPQiYCpU1nKcqOoULWr2cA+FVjfUCwKBpunuEdoQXB6NMHGl4hSdTf85rN4cSzWUBjPWJqyglwxHsGGxydDkgLt9BmrYPtEAh1TDNnxUgEOh3r01TvY296Ke7aGuatr24hKycHmvlk2Qj8+caSNPe8y/leEbc1XIpbsHmT3AImf9JhnVrJD6D9eKSYbQrdgTzRSfpVY0jnJ1HDmJGvfSCapQh6kv3MPCbk/x43DyDpc0S/7VjPxgkk0+B0rq0RRd7dH9RTnU2Pr/+WPSzOAy9WV5r0DnW2j/cTqGxBvgy6Z5vMwuSJQ/dTl2JwZ3+C8iD5xI7epPLwmo2I7Nuek/G2HhoLazniYUby/IEuXIgECtz+1oJuocvnuCosXv6Ft1qWUCAwEAAQ==
-----END PUBLIC KEY-----

Liityntäagentin julkinen avain tuotantoympäristöön

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAvzAqMRPZeWrLc+udHyccUB+xuEdNQusYm8fSSSLCWCPg+fcqO82uN7b4dV30aFsc+F+7zNIHCIhxtXO4Kmg3fASSJHeXO/9Ok8Q9+dCPV/cjzd40qXRLwQl8aomhjjXDMtFqBABGISxANjzSKHHAvfJ7mhY769cx0bHLRKsA47NInxlyIB6z4APF5q6lmuJmGQeZ+Qg3JZt7THPbTeslrOilov4eth8eL51gVmfudLT/Mpha2nQ4vDIBWj6fw+SmiTq0I/C9UOW7W+TSnqoripFJr760AudIYA3kkSI5cIKa+ryqPYWXDQk2ZNA4ZQp6Bo3dsDK2+kNWY9FiHS/zRuLZMzdEIrT436NlkxiGdtjt9yrd5pmIMtH0n51TALWqVgicCUBaqLXAqk9YYV4RLd6rH4XRv3u4uNRyx1VFy7Em7grTOdUYwnurN3wQYW63FD9JbCPhR2qzCbS+t4C8x0P8XBjtXww25DvPv/UX5pKtaJkACHYnHMekAY1G2WJE+TjnehAHXj1ylZ9031UgIJfPLYiRislrffsFr7t36Z1r3eSvoljDzfXfVAuVnhizLdaes1HyL3rA3RwtWTwz7JCb2OasGKaZmCOgyCtus9l7u+vV4Aa3N9p4U0UQbBsgrggKahmhLX4W4FrUl4yLu4DB2i6YwXKeEb5zoTeWZWUCAwEAAQ==
-----END PUBLIC KEY-----

Liityntäagentin metadata julkisen avaimen lisäyksen jälkeen

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" ID="_CEE5C7D08DD8B3551E3232020FE394C729769927" entityID="https://kapa.rova.fi/valtuutus-veroconnector-test2">
	<md:SPSSODescriptor WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
		<md:KeyDescriptor use="signing">
			<ds:KeyInfo>
				<ds:X509Data>					<ds:X509Certificate>MIIFnTCCA4WgAwIBAgIEKPKnSzANBgkqhkiG9w0BAQsFADB/MQswCQYDVQQGEwJmaTEQMA4GA1UECBMHVXVzaW1hYTERMA8GA1UEBxMISGVsc2lua2kxDDAKBgNVBAoTA1ZSSzEaMBgGA1UECxMRQXNpb2ludGl2YWx0dXVkZXQxITAfBgNVBAMTGHJvbGVzLWF1dGhzLWthcnZhLWNsaWVudDAeFw0xNzExMDkwOTI0NDVaFw0yNzExMDcwOTI0NDVaMH8xCzAJBgNVBAYTAmZpMRAwDgYDVQQIEwdVdXNpbWFhMREwDwYDVQQHEwhIZWxzaW5raTEMMAoGA1UEChMDVlJLMRowGAYDVQQLExFBc2lvaW50aXZhbHR1dWRldDEhMB8GA1UEAxMYcm9sZXMtYXV0aHMta2FydmEtY2xpZW50MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAvzAqMRPZeWrLc+udHyccUB+xuEdNQusYm8fSSSLCWCPg+fcqO82uN7b4dV30aFsc+F+7zNIHCIhxtXO4Kmg3fASSJHeXO/9Ok8Q9+dCPV/cjzd40qXRLwQl8aomhjjXDMtFqBABGISxANjzSKHHAvfJ7mhY769cx0bHLRKsA47NInxlyIB6z4APF5q6lmuJmGQeZ+Qg3JZt7THPbTeslrOilov4eth8eL51gVmfudLT/Mpha2nQ4vDIBWj6fw+SmiTq0I/C9UOW7W+TSnqoripFJr760AudIYA3kkSI5cIKa+ryqPYWXDQk2ZNA4ZQp6Bo3dsDK2+kNWY9FiHS/zRuLZMzdEIrT436NlkxiGdtjt9yrd5pmIMtH0n51TALWqVgicCUBaqLXAqk9YYV4RLd6rH4XRv3u4uNRyx1VFy7Em7grTOdUYwnurN3wQYW63FD9JbCPhR2qzCbS+t4C8x0P8XBjtXww25DvPv/UX5pKtaJkACHYnHMekAY1G2WJE+TjnehAHXj1ylZ9031UgIJfPLYiRislrffsFr7t36Z1r3eSvoljDzfXfVAuVnhizLdaes1HyL3rA3RwtWTwz7JCb2OasGKaZmCOgyCtus9l7u+vV4Aa3N9p4U0UQbBsgrggKahmhLX4W4FrUl4yLu4DB2i6YwXKeEb5zoTeWZWUCAwEAAaMhMB8wHQYDVR0OBBYEFORJ4Ov5IMJsoAlCM2GZ/RO/W6M4MA0GCSqGSIb3DQEBCwUAA4ICAQC0qu97XRcCkPKWqWRKr5z4UHEkwjcEX6793f92Gy4hL960YpEyby6LXYtUhaRBphryNDl5DWHE9YpgQGy37Uk93s/xZFah84VswbAr60Es3MQznCFmWnGPQp1q+9KwgQ2+eTMuXrqA8v2JlptW+PHAMnT2dnutp16AQQrk+UhYRjYhbGSJDMDAU+ScITFOlMmd5vZjth4Imp8Ofk+ajOUIdQd8RtttUhUdmG/agarWXZYTBYxSCzf9gkwLTmlBpR7wTcHr9UsxCXkU+p1QACssDCHq4BNiaT+PwDVRTAxof0XJtrcQYYO4UWX9f3EBDFJsdgQTLAmhXzdGxJHITP8RZahPSGwvcpNAcJB+gTlniZeXovT7PZvMZ1pxuJtwdxs9i4AK5HANXUGtnZzxeQa9SRbwwKg40l9idf8Yuu7wydM6ertElWYvMlgCyeBIKRL6j4Uro5OkLUUnCj9V7Rb2ftMvX7g/MbU7dqx8sBHx/xpkiBVcRjRYgF+Y2dDT9I03ZMroAIhk1MQwseNXM1v+LUAix3RR/2k+CIT/HnNiJiCfEN9Ky+wQxTnmHEYMpVwm1jmtTDiI8UG5jFsZFur0oM8tZjgqF4qSxlZj/4ZcXckrfkD91LJt5u5QvGyU56uTRExyyHY54ESpEbahJ7v1RvX/JLcazJwfhdL1Mvav8w== </ds:X509Certificate>
				</ds:X509Data>
			</ds:KeyInfo>
		</md:KeyDescriptor>
		<md:KeyDescriptor use="signing">
			<ds:KeyInfo>
				<ds:KeyValue>
					<ds:RSAKeyValue>
						<ds:Modulus>AKEqpiQ/9J9ZYQITmjrYq3sAwXz6bTQg/yff2sjkZR9uC4NCxWVqAXaxZkGNfioDn7eYOpSzLlfzanCHR0am2NlxKEV4Cc5s71mvYAlUE2+91z/MAIGXORDuohmWv1oxNqmVLYIiPXqvz85nbguVB/fgdBlDN+5xoXa4DT/R8Gf1udC490C6gTtfzVg2mNI+0UwFTXWtQrK40Xh8DpKCGjPHcvTU6t+OyjBXUAxEHi5l5KIygoe8CHnt+fOPdlA6LJPQS+HchnGxWYC9CjTJm3E+rZXedxJFajbByv4gTBT0ImAqVNZynKjqFC1q9nAPhVY31AsCgabp7hHaEFwejTBxpeIUnU3/OazeHEs1lAYz1iasoJcMR7BhscnQ5IC7fQZq2D7RAIdUwzZ8VIBDod69NU72Nveinu2hrmra9uISsnB5r5ZNkI/PnGkjT3vMv5XhG3NVyKW7B5k9wCJn/SYZ1ayQ+g/XikmG0K3YE80Un6VWNI5ydRw5iRr30gmqUIepL9zDwm5P8eNw8g6XNEv+1Yz8YJJNPgdK6tEUXe3R/UU51Nj6//lj0szgMvVlea9A51to/3E6hsQb4MumebzMLkiUP3U5dicGd/gvIg+cSO3qTy8JqNiOzbnpPxth4aC2s54mFG8vyBLlyIBArc/taCbqHL57gqLF7+hbdall </ds:Modulus>
						<ds:Exponent>AQAB</ds:Exponent>
					</ds:RSAKeyValue>
				</ds:KeyValue>
			</ds:KeyInfo>
		</md:KeyDescriptor>
		<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
		<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://kapa.rova.fi/valtuutus-veroconnector-test2" index="0" isDefault="true"/>
	</md:SPSSODescriptor>
</md:EntityDescriptor>

KaSu-ominaisuuden testaaminen

KaSu-ominaisuuden testaaminen Suomi.fi-valtuuksien asiakastestiympäristössä ei ole välttämätöntä, mutta organisaatio voi niin tehdä halutessaan.

Katson testiympäristöstä löytyy valmiiksi hetulle 060896-999A rooli ”all”, minkä avulla voi testata KaSu-ominaisuutta. Tällä hetulla palautuu valtuuskyselyissä kaikki valtuuskoodit, jotka palvelukonfiguraatioon on luvitettu ja joihin on liitetty ”all” rooli.

Uusien testi-identiteettien luominen Katson testiympäristöön tapahtuu näin alla olevan ohjeen mukaan. Testihetuina on käytettävä Suomi.fi-valtuuksien testiaineistosta löytyviä henkilötunnuksia.

Ohje hyödyntäjäorganisaatioille testitunnisteiden tuottamiseksi Katson HTEST-ympäristöön

Katso-testiympäristöön voi perustaa testitunnisteita haluamillanne testihetuilla. Tätä varten tarvitsette testiympäristöön ensin pääkäyttäjyyden, jotta voitte tarvittavia valtuutuksia myöntää. Pääkäyttäjä luo alitunnisteita, jotka voi vahventaa Katso-tunnisteiksi haluamillanne hetuilla ja joille tarvittavia valtuutuksia voi myöntää. Tässä testitunnisteaihiot pääkäyttäjyyden perustamiseksi osoitteessa https://htesti.katso.tunnistus.fi/.

  • 170107A942Y
  • 6650710-3

Pääkäyttäjyyden perustamisen yhteydessä vaiheessa 1/7 tulee valita vaihtoehto ”Käyn henkilökohtaisesti palvelupisteessä”. Pääkäyttäjyyden ja testitunnisteiden vahvennuksen aktivoinnin voit pyytää esim. vastaamalla tähän viestiin tai osoitteella jl.tunnistustiimi (a) vero.fi.

Tuotannon Katso-ohjeita voi soveltaa testiympäristöön https://www.vero.fi/tietoa-verohallinnosta/yhteystiedot-ja-asiointi/asioi-verkossa/katso/kayttajan_ohjee/katsopalvelun_yksityiskohtaiset_ohjee/