2008-04-17 1 (13) Virtu - Määrittely Attribuuttien muodostamisen ohjeistus
2008-04-17 2 (13) Sisällysluettelo 1 Johdanto... 4 2 Yhteiset luottamusverkoston attribuutit... 4 3 Uuden attribuutin muodostaminen Virtu-federaatioon yhteensopivaksi... 4 3.1 Esimerkkinä LDAP-attribuutista SAML Attribute Assertionin muodostaminen... 4 3.1.1 OID:n muodostaminen... 4 3.1.2 Semantiikan määrittely Virtussa...5 3.1.3 SAML Attribute Assertion esimerkki... 5 3.1.4 Julkaisu... 5 3.2 Esimerkkinä uuden attribuutin muodostaminen omaa koodistoa käyttäen... 5 3.2.1 OID:n muodostaminen... 5 3.2.2 Semantiikan määrittely Virtussa...6 3.2.3 SAML Attribute Assertion esimerkki... 6 3.2.4 Julkaisu... 6 4 Virtu-skeeman pakollisten ja suositeltavien attribuuttien soveltamisen ohjeistus... 6 4.1 virtupersonprincipalname... 6 4.1.1 OID... 6 4.1.2 Semantiikka... 6 4.1.3 SAML esimerkki virtupersonprincipalname... 7 4.1.4 Julkaisu... 7 4.2 virtupersonentitlement... 7 4.2.1 OID... 7 4.2.2 Semantiikka... 7 4.2.3 SAML esimerkki virtupersonentitlement... 7 4.2.4 Julkaisu... 8 4.3 virtuorgnumber... 8 4.3.1 OID... 8 4.3.2 Semantiikka... 8 4.3.3 SAML esimerkki virtuorgnumber... 8 4.3.4 Julkaisu... 8 4.4 virtuhomeorganization... 8 4.4.1 OID... 8 4.4.2 Semantiikka... 8 4.4.3 SAML esimerkki virtuhomeorganization... 9 4.4.4 Julkaisu... 9 4.5 virtuhomeorganizationtype... 9 4.5.1 OID... 9 4.5.2 Semantiikka... 9 4.5.3 SAML esimerkki virtuhomeorganizationtype... 9 4.5.4 Julkaisu... 10 4.6 cn... 10 4.6.1 OID... 10 4.6.2 Semantiikka... 10 4.6.3 SAML esimerkki cn... 10 4.6.4 Julkaisu... 10
2008-04-17 3 (13) 4.7 sn... 10 4.7.1 OID... 10 4.7.2 Semantiikka... 10 4.7.3 SAML esimerkki sn... 10 4.7.4 Julkaisu... 11 4.8 employeenumber... 11 4.8.1 OID... 11 4.8.2 Semantiikka... 11 4.8.3 SAML esimerkki employeenumber... 11 4.8.4 Julkaisu... 11 4.9 mail... 11 4.9.1 OID... 11 4.9.2 Semantiikka... 11 4.9.3 SAML esimerkki employeenumber... 11 4.9.4 Julkaisu... 11 5 Soveltamisohje... 12 6 Liitteet... 12 6.1 Liite 1: Lista Virtu-skeeman attribuuteista... 12
2008-04-17 4 (13) Attribuuttien muodostaminen ja käyttö Virtu-federaatiossa 1 Johdanto Dokumentissa kuvataan attribuuttien muoto ja muodostaminen Virtu-federaatiossa. Määrittelyn tarkoitus on myös kuvata miten laajentaa skeemaa kahdenkeskisillä attribuuteilla Virtu-federaation kanssa yhteensopivalla tavalla. Attribuuttien muodostaminen ohjeistuksen mukaan mahdollistaa kyseisen attribuutin käyttöönoton myöhemmin virallisessa Virtu-federaation skeemassa. Tästä on hyötynä se, että käyttäjäorganisaatiot ja palveluntuottajat pystyvät yhteisesti sopimaan tarvittavan tietosisällön välittämisestä ja julkaisemaan sen muille valmiiksi mietittynä. 2 Yhteiset luottamusverkoston attribuutit Virtu-federaatio julkaisee oman Virtu-skeemansa, joka perustuu Hakemistotiedot ja niiden ylläpito - suositukseen JHS 133 1. Virtu-skeemassa on attribuutteja, joita tarvitaan osapuolten kesken yksilöimään ja kuvaamaan käyttäjiä käyttävässä organisaatiossa. Virtu-federaatio tulee käyttämään OID tunnistesarjaa X.Y.Z määrittelemilleen attribuuteille. Nämä ovat lueteltu liitteessä 1. Attribuutit ovat oletusarvoisesti moniarvoisia, jos asiaa ei ole erikseen tarkennettu. Esimerkeissä annetaan malli arvojoukon välittämisestä. 3 Uuden attribuutin muodostaminen Virtu-federaatioon yhteensopivaksi Muodostamissääntö: 1 Selvitä attribuutin tai määritä itse OID. Yksilöivä OID tunniste voidaan luoda koodistolle JHS 159 2 standardia noudattaen. 2 Kuvaa attribuutin arvot, niiden merkitykset ja käyttötilanteet suhteessa henkilöön Virtu-federaatiosta. 3 Muodosta esimerkki SAML 2.0 Attribute Assertionista malliksi todenmukaisessa käyttötilanteessa 4 Julkaise kuvaus ja esimerkki Virtu-federaation julkaisualustalla 3.1 Esimerkkinä LDAP-attribuutista SAML Attribute Assertionin muodostaminen Seuraavassa käydään läpi vaiheittain edellä kuvatut vaiheet. 3.1.1 OID:n muodostaminen Tarkastellaan givenname attribuuttia, joka kuuluu X.500 käyttäjä (person) skeemaan, joka on määritelty RFC2256 ja sen myöhemmin korvanneessa RFC5126 3 :ssä. Kyseisessä määrittelyssä givenname attribuutille on määritelty OID 2.5.4.42. 1 JHS 133 Hakemistotiedot ja niiden ylläpito, http://www.jhs-suositukset.fi/web/guest/jhs/recommendations/133 2 JHS 159 ISO OID-yksilöintitunnuksen soveltaminen julkishallinnossa, http://www.jhssuositukset.fi/web/guest/jhs/recommendations/abstracts#jhs159
2008-04-17 5 (13) 3.1.2 Semantiikan määrittely Virtussa Kuvaus käytöstä: Attribuutin arvoina ovat henkilön etunimet, joita käytetään palvelun käyttöliittymässä esittämässä käyttäjää. Kun attribuuttia käytetään, se sisältää arvon. JHS 133 suosituksessa poiketaan RFC 2256 vastaavan attribuutin määrittelystä siltä osin, että se voi sisältää kaikki etunimet. 3.1.3 SAML Attribute Assertion esimerkki 3.1.4 Julkaisu SAML 2.0 -profiilimäärittelyssä velvoitetaan, että attribuutit nimetään yksikäsitteisesti seuraavasti sekaannusten välttämiseksi. Attribuutin name arvo muodostetaan URN:ksi RFC 3061 4 dokumentin kuvaamalla käytännöllä, jossa liitetään urn:oid: tunniste alkuun ja attribuutin OID tunniste loppuun. <saml:attribute name="urn:oid:2.5.4.42" friendlyname="givenname"> <saml:attributevalue>tauno</saml:attributevalue> FriendlyName ja sen arvo givenname ovat vain ohjeellisena tunnisteena attribuutissa. Sitä ei käytetä osapuolien välisessä tietojen vaihdossa. Sen käyttö on vapaaehtoista, mutta käyttämisen etuna on attribuutin tulkinnan tai tunnistamisen helpottaminen virhetilanteiden jäljittämisessä. Attribuuttimääritys julkaistaan Virtu-federaation kotisivuilla formaalissa muodossa selityksineen. 3.2 Esimerkkinä uuden attribuutin muodostaminen omaa koodistoa käyttäen Tarpeena on välittää Virtu-operaattorin yhteiskäyttöiselle palvelulle yhteyshenkilön toimenkuva organisaatiossa suhteessa Virtu-federaatioon. 3.2.1 OID:n muodostaminen Virtu-koordinaattori on varannut oman OID avaruuden, josta se on varannut koodistolle tunnisteen X.Y.Z.2.1.1. Kyseistä OID-avaruutta käytetään myöhemmin tässä dokumentissa oleville attribuuteille ja käytöstä vastaa Virtu-koordinaattori. Jos 3 RFC5126, Lightweight Directory Access Protocol (LDAP): Schema for User Applications A. Sciberras, Ed. [ Kesäkuu 2006 ] (vahentanut RFC2256), ftp://ftp.rfc-editor.org/in-notes/rfc5126.txt 4 RFC3061, A URN Namespace of Object Identifiers M. Mealling [ Helmikuu 2001 ] (vanhentanut RFC3001), ftp://ftp.rfceditor.org/in-notes/rfc3061.txt
2008-04-17 6 (13) organisaatiolla ei ole ennestään varattu omaa OID-aliavaruutta, sellainen on haettavissa esimerkiksi Suomen Standardisoimisliitto SFS ry kautta 5 tai IANAlta 6. 3.2.2 Semantiikan määrittely Virtussa Attribuutilla kuvataan henkilön toimenkuva organisaatiossa suhteessa Virtufederaatioon. Sanasto on hallinnollinen yhteyshenkilö, tekninen yhteyshenkilö ja laskutusyhteyshenkilö. 3.2.3 SAML Attribute Assertion esimerkki 3.2.4 Julkaisu <saml:attribute name="urn:oid:x.y.z.2.1.1" friendlyname="virtuorgcontacttype"> <saml:attributevalue>hallinnollinen yhteishenkilö</saml:attributevalue> Virtu-operaattorin palvelun tuottaja ylläpitää sivustollaan määrittelyä, johon on linkki Virtu federaation skeemakuvauksen yhteydessä Virtu-federaation kotisivuilla. 4 Virtu-skeeman pakollisten ja suositeltavien attribuuttien soveltamisen ohjeistus 4.1 virtupersonprincipalname 4.1.1 OID 4.1.2 Semantiikka virtupersonprincipalname attribuutin OID tunniste on: X.Y.Z.1.2 Käyttäjän yksilöivä tunniste Virtu-federaatiossa. On tai on ollut liitettynä yhteen henkilöön domainissa. Arvon muoto: alkuosa + erotinmerkki + domain Attribuutin tulee olla yksiarvoinen. Erotinmerkkinä käytetään prosenttimerkkiä (%) ja se saa esiintyä vain kerran arvossa. Alkuosan muodon organisaatio määrittää itsenäisesti. Vaatimuksena on, ettei samaa tunnistetta uudelleen käytetä eri henkilölle. Jälkiosa on Virtu-kotiorganisaation rekisteröinnin yhteydessä Virtu-federaation operaattorille ilmoittama DNS nimiavaruus. DNS nimiavaruuksia voi olla useita. 5 SFS, Kortinantajan-, AID-, RID-,OID- ja NSAP-tunnukset, http://www.sfs.fi/palvelut/tunnukset/ 6 IANA, Private Enterprise Number (PEN) Request Template, http://pen.iana.org/pen/penapplication.page
2008-04-17 7 (13) 4.1.3 SAML esimerkki virtupersonprincipalname 4.1.4 Julkaisu Arvon muodostamisessa organisaatio käyttää itse määrittelemäänsä sääntöä, joka täyttää semantiikan ja vaatimukset. Esimerkkinä Tauno Tammen tunniste, joka on muodostettu vuonna 2008 käyttäen tietojärjestelmän käyttäjätunnusta ttammi. Virasto Y on rekisteröinyt toimialueensa virastoy.fi tunnisteena, jota he hallinnoivat. <saml:attribute name="urn:oid: X.Y.Z.1.2" friendlyname=" virtupersonprincipalname"> <saml:attributevalue>2008ttammi%virastoy.fi</saml:attributevalue> 4.2 virtupersonentitlement 4.2.1 OID 4.2.2 Semantiikka virtupersonentitlement attribuutin OID tunniste on: X.Y.Z.1.4 Luettelo resursseista, joihin käyttäjälllä on käyttöoikeus ja mahdollinen rooli-informaatio. Arvojoukko on moniarvoinen. Kyseinen URL-tunniste voi olla keinotekoinen, kunhan se on yksilöllinen eikä ole päällekkäinen toisen organisaation kanssa tai viittaa toisen organisaation hallinnoimaan verkkopalveluun. 4.2.3 SAML esimerkki virtupersonentitlement Moniarvoinen välittäminen Virtu-federaatiossa 7. <saml:attribute name="urn:oid:x.y.z.1.4" friendlyname="virtupersonentitlement "> <saml:attributevalue>http://valtiokonttori.fi/rondo/tty/1234/hyvaksyja </saml:attributevalue> <saml:attribute name="urn:oid:x.y.z.1.4" friendlyname="virtupersonentitlement "> <saml:attributevalue>http://secure.personec.com/travel/vk/3244/matkasihteeri </saml:attributevalue> 7 Saattaa muuttua, jos ilmenee teknisiä yhteensopivuusongelmia eri toteutusten välillä. Vaihtoehtoisia tapoja on esitetty: Feide-federation: How SAML 2.0 is used in Feide, http://rnd.feide.no/content/how-saml-20-used-feide, [9.4.2008] Katso-Karva: Katso-kirjautuminen ja Karva-roolikysely, Karva-roolikyselyn määrittely, SAML 2.0 attribuuttikyselyn vastausviesti, sivut 6 ja 10, http://www.vero.fi/nc/doc/download.asp?id=5642;66156, [9.4.2008]
2008-04-17 8 (13) 4.2.4 Julkaisu 4.3 virtuorgnumber 4.3.1 OID 4.3.2 Semantiikka Virtu-skeemakuvauksen yhteydessä Virtu-federaation kotisivuilla, josta löytyy tieto tai linkit eri palveluntarjoajien auktorisointitunnisteisiin. virtuorgnumber attribuutin OID tunniste on: X.Y.Z.1.3 Henkilön kotiorganisaation y-tunnus. Virtu-federaation käyttämä organisaatiotunniste perustuu patentti- ja rekisterihallituksen yritys- ja yhteisötunnukseen. Muotona käytettään JHS 159 suositusta y-tunnuksen esittämisessä OID muodossa, missä tarkistusnumeron erotinviiva poistetaan ja 7-numeroisessa tunnuksessa ei käytetä etunollaa. Attribuutin tulee olla yksiarvoinen. 4.3.3 SAML esimerkki virtuorgnumber 4.3.4 Julkaisu Turun kaupungin y-tunnuksesta 204819-8 johdettu esimerkki. <saml:attribute name="urn:oid:x.y.z.1.3" friendlyname="virtuorgnumber"> <saml:attributevalue>1.2.246.10.2048198</saml:attributevalue> 4.4 virtuhomeorganization 4.4.1 OID 4.4.2 Semantiikka virtuhomeorganization attribuutin OID tunniste on: X.Y.Z.1.5 Organisaation DNS domain tunnukseen perustuva tunniste, joka voi sisältää tarkemman hierarkian tarvittaessa. Attribuutin arvolla voidaan kuvata henkilön sijainti organisaatiossa tarkalla tasolla. Loppuosan on oltava sama kuin virtupersonprincipalname-attribuutin arvon domainosa.
2008-04-17 9 (13) 4.4.3 SAML esimerkki virtuhomeorganization 4.4.4 Julkaisu <saml:attribute name="urn:oid:x.y.z.1.5" friendlyname="virtuhomeorganization"> <saml:attributevalue>esikunta.virastoy.fi</saml:attributevalue> 4.5 virtuhomeorganizationtype 4.5.1 OID 4.5.2 Semantiikka virtuhomeorganizationtype attribuutin OID tunniste on: X.Y.Z.1.6 Henkilöön liittyvä organisaation tyyppi, jota käytetään valtuuttamisessa. Organisaation suhdetta julkishallintoon kuvaava sanasto: valtionhallinto, kunnallishallinto, valillinen-hallinto ja muu. Organisaation tyyppiä kuvaava sanasto: ministerio, virasto, liikelaitos, kunta, kuntayhtyma osakeyhtio ja muu-organisaatio. Arvolle muu on varattu erityinen merkitys, jos suhdetta julkishallintoon ei ole määriteltävissä. Arvoa muu-organisaatio käytetään organisaation tyyppiä kuvaavana silloin, jos sopivaa ei löydy Virtu-skeemamäärittelyn sanastosta. Sanastojen sallittuja arvoja lisätään tarpeen mukaan. HUOM! On varauduttava, että palautettavia arvoja on monta.vain 7-bittisen ASCII merkistön arvot ovat sallittuja. Arvot eivät sisällä skandinaavisia merkkejä vaan ne konvertoidaan; Ä->A, å ->a, ä->a, ö->o jne periaatteella. 4.5.3 SAML esimerkki virtuhomeorganizationtype Valtion virastoa kuvaava esimerkki <saml:attribute name="urn:oid: X.Y.Z.1.6" friendlyname="virtuhomeorganizationtype"> <saml:attributevalue>valtionhallinto</saml:attributevalue> <saml:attribute name="urn:oid: X.Y.Z.1.6" friendlyname="virtuhomeorganizationtype"> <saml:attributevalue>virasto</saml:attributevalue> Kuntaa kuvaava esimerkki:
2008-04-17 10 (13) 4.5.4 Julkaisu 4.6 cn 4.6.1 OID 4.6.2 Semantiikka 4.6.3 SAML esimerkki cn 4.6.4 Julkaisu 4.7 sn 4.7.1 OID 4.7.2 Semantiikka 4.7.3 SAML esimerkki sn <saml:attribute name="urn:oid: X.Y.Z.1.6" friendlyname="virtuhomeorganizationtype"> <saml:attributevalue>kunnallishallinto</saml:attributevalue> <saml:attribute name="urn:oid: X.Y.Z.1.6" friendlyname="virtuhomeorganizationtype"> <saml:attributevalue>kunta</saml:attributevalue> Virtu-skeemakuvauksen yhteydessä Virtu-federaation kotisivuilla sanastoineen. cn attribuutin OID tunniste on: 2.5.4.3 Henkilön koko nimi JHS 133 mukaisesti. <saml:attribute name="urn:oid:2.5.4.3" friendlyname="cn"> <saml:attributevalue>tammi Tauno Antero</saml:AttributeValue> sn attribuutin OID tunniste on: 2.5.4.4 Henkilön sukunimi suosituksen JHS 133 mukaisesti. <saml:attribute name="urn:oid:2.5.4.4" friendlyname="sn"> <saml:attributevalue>tammi</saml:attributevalue>
2008-04-17 11 (13) 4.7.4 Julkaisu 4.8 employeenumber 4.8.1 OID 4.8.2 Semantiikka employeenumber attribuutin OID tunniste on: 2.16.840.1.113730.3.1.3 Organisaation myöntämä henkilönumero, jonka avulla henkilön muun tunnisteen muuttuminen pystytään havaitsemaan. Yksilöllinen eikä liitettävissä toiseen henkilöön. Suositellaan käytettäväksi henkilöstöhallinnon numeroa. Attribuutin tulee olla yksiarvoinen. 4.8.3 SAML esimerkki employeenumber 4.8.4 Julkaisu 4.9 mail 4.9.1 OID 4.9.2 Semantiikka <saml:attribute name="urn:oid:2.16.840.1.113730.3.1.3" friendlyname="employeenumber"> <saml:attributevalue>92003011</saml:attributevalue> mail attribuutin OID tunniste on: 0.9.2342.19200300.100.1.3 Organisaation henkilölle myöntämä ajantasainen sähköpostiosoite. 4.9.3 SAML esimerkki employeenumber 4.9.4 Julkaisu <saml:attribute name="urn:oid: 0.9.2342.19200300.100.1.3" friendlyname="mail"> <saml:attributevalue>tauno.tammi@virastoy.fi</saml:attributevalue>
2008-04-17 12 (13) 5 Soveltamisohje 6 Liitteet Jos myöhemmässä vaiheessa tarvitaan uusi attribuutti, tai ilmenee päällekkäisiä vastaavaan tarkoitukseen tarkoitettuja attribuutteja, noudatetaan priorisoinnissa seuraavaa järjestystä: 1 Virallista Virtu-skeeman määritystä 2 X.500 person skeeman luokista -(esim. inetorgperson) johdettua attribuuttia 3 Vastaavaa Virtu-federaatiossa julkaistua skeeman ulkopuolista attribuuttia 4 Omaa attribuuttia ja sen koodistoa 6.1 Liite 1: Lista Virtu-skeeman attribuuteista
2008-04-17 13 (13) LIITE 1: Lista Virtu-skeeman attribuuteista Henkilön tieto Attribuutti OID URN Pakollisuus A*) JUHTA JHS 133 Henkilön nimi cn 2.5.4.3 urn:oid:2.5.4.3 MUST Sukunimi sn 2.5.4.4 urn:oid:2.5.4.4 MUST Etunimi / etunimet givenname 2.5.4.42 urn:oid:2.5.4.42 MUST Sähköpostiosoite mail 0.9.2342.19200300.100.1.3 urn:oid:0.9.2342.19200300.100.1.3 RECOMMENDED Puhelinnumero telephonenumber 2.5.4.20 urn:oid:2.5.4.20 MAY Organisaation nimi o 2.5.4.10 urn:oid:2.5.4.10 OPTIONAL Organisaation yksikön nimi ou 2.5.4.11 urn:oid:2.5.4.11 OPTIONAL Faksinumero facsimiletelephonenumber 2.5.4.23 urn:oid:2.5.4.23 OPTIONAL Katuosoite street 2.5.4.9 urn:oid:2.5.4.9 OPTIONAL Postilokero postofficebox 2.5.4.18 urn:oid:2.5.4.18 OPTIONAL Postinumero postalcode 2.5.4.17 urn:oid:2.5.4.17 OPTIONAL Postiosoite postaladdress 2.5.4.16 urn:oid:2.5.4.16 OPTIONAL Paikkakunta l 2.5.4.7 urn:oid:2.5.4.7 OPTIONAL Kuvaus description 2.5.4.13 urn:oid:2.5.4.13 OPTIONAL Toimiala businesscategory 2.5.4.15 urn:oid:2.5.4.15 OPTIONAL Organisaatiovarmenne (henk.koht.) usercertificate 2.5.4.36 urn:oid:2.5.4.36 OPTIONAL Virtu laajennokset Henkilönyksillöintitunniste virtupersonprincipalname X.Y.Z.1.2 urn:oid:x.y.z.1.2 MUST X Organisaation yksilöivänumero virtuorgnumber X.Y.Z.1.3 urn:oid:x.y.z.1.3 MUST X Henkilön valtuutukset virtupersonentitlement X.Y.Z.1.4 urn:oid:x.y.z.1.4 RECOMMENDED X Kodin postiosoite homepostaladdress 0.9.2342.19200300.100.1.39 urn:oid:0.9.2342.19200300.100.1.39 OPTIONAL Kotipuhelinnumero homephone 0.9.2342.19200300.100.1.20 urn:oid:0.9.2342.19200300.100.1.20 OPTIONAL Kotiorganisaatio virtuhomeorganization X.Y.Z.1.5 urn:oid:x.y.z.1.5 RECOMMENDED X Henkilökuntanumero employeenumber 2.16.840.1.113730.3.1.3 urn:oid:2.16.840.1.113730.3.1.3 RECOMMENDED X Työsuhteen tyyppi virtuemployeetype X.Y.Z.1.6 urn:oid:x.y.z.1.6 MAY X Titteli title 2.5.4.12 urn:oid:2.5.4.12 MAY Kotiorganisaation tyyppi virtuhomeorganizationtype X.Y.Z.1.7 urn:oid:x.y.z.1.7 MUST X *) Auktorisointiattribuutteja käytetään valtuuttamiseen