Retningslinjer for integrasjon med ID-porten
Innhold Innhold... 2 1 Installasjon av programvare for føderering... 3 2 Hvordan identifisere tjenester som skal fødereres... 3 3 Beskyttelse av tjenester gjennom nodeløsningen... 3 4 Sette sikkerhetsnivå for beskyttet tjeneste... 3 5 Konfigurering av metadata og føderering... 4 5.1 Krav til nøkler... 4 5.2 Protokoller og NameIDFormat... 4 6 Innmelding i ID-portens Circle of Trust... 5 7 Verifisering av føderering... 5 8 Migrering fra verifikasjonsmiljø til produksjon... 6 9 Logging... 6 10 Tegnsett... 6 11 Konfigurasjon av sesjon... 6 12 Caching av SAML meldinger... 7 13 Tidssynkronisering... 7 14 Enkoding av meldinger... 7 15 IP-adresser... 7 16 Logo til tjenesteeier i ID-porten... 8 Vedlegg1: Eksempel på metadatafil... 9
Historikk Rev. Dato Endret av Kommentar 0.1 28.09.2010 Daniel Lerum Første versjon 1
Innhold ID-porten tilbyr tjenesteeiere en sikker løsning for autentisering. For å få til en vellykket føderering må både ID-porten og tjenesteeier åpne visse tjenester for integrasjon. For at dette skal fungere i praksis er det ytterst viktig at alle standarder og retningslinjer følges. 2
1 Installasjon av programvare for føderering Alle tjenesteeiere må implementere en node-løsning som støtter SAMLv2. Typisk involverer dette installasjon av software som gir SAMLv2-kompatibel kommunikasjon mot ID-porten. Difi har laget en liste over leverandører som tilbyr integrasjonmoduler med ID-porten og som har foretatt integrasjon som Difi har verifisert, se: http://samarbeidsportalen.difi.no/samfagom.aspx?m=53780&amid=2497486 2 Hvordan identifisere tjenester som skal fødereres Å identifisere hvilke tjenester som skal fødereres innebærer å samle informasjon om disse. Hvilken informasjon som er relevant avhenger av hvilken programvare som er valgt for føderering, men vil typisk inkludere DNS-navn og URL ene til hvor tjenesten er eksponert. 3 Beskyttelse av tjenester gjennom nodeløsningen Tjenester må beskyttes ved at de indikerer ovenfor fødereringsprogramvaren at autentiseringen skal håndteres av hub-en (ID-porten). Hvordan dette gjøres, vil variere fra produkt til produkt, og kan involvere skreddersøm av systemet eller konfigurasjon av container for webløsningen/tjenesteapplikasjonen. 4 Sette sikkerhetsnivå for beskyttet tjeneste Tjenester som er beskyttet av ID-porten har mulighet for å sette et minimums sikkerhetsnivå for autentisering. Dette fordi tjenester i forvaltningen har ulik grad av sensitivitet. Det er opp til tjenesteeier å definere hvilket sikkerhetsnivå som tilfredstiller den enkelte tjeneste. Minimum sikkerhetsnivå settes med Authentication Context i AuthnRequest i SAML. Se Tilslutningsguide mot IDporten 2.0 for mer detaljer om sikkerhetsnivå. Programvaren for SAMLv2 føderering må konfigureres slik at den godtar IDporten sertifikatene. ID-portens serversertifikat for SSL-kommunikasjon mellom tjenesteeiers server og ID-portens server ved SAML SOAPkommunikasjon er utstedt av DigiCert. SAML HTTP Artifact og SAML SOAP bindingene må sikres med SSL både for SSO og SLO profilene. Det samme gjelder alle andre sider innenfor den sikre løsningen. Alle endepunkter hos tjenesteeierne og identitetsleverandøren må derfor ha installert sertifikater på tjenersiden. 3
5 Konfigurering av metadata og føderering Tjenesteeier definerer selv i metadata som utveksles med ID-porten hvilke meldinger som skal signeres og krypteres. ID-porten krever at selve metadatene er signert ved overrekkelse, men også at følgende element må signeres av tjenesteeier ved SAML-kommunikasjon: Authentication request Artifact resolve SingleLogout request SingleLogout response Og ID-porten vil selv signere: Artifact response o som inneholder ett kryptert Assertion-elementet. SingleLogout request SingleLogout response Tjenesteeier må sette dette ved å angi følgende i SPSSODescriptor i metadata: AuthnRequestsSigned="true" vil si at tjenesteeier vil signere sine autentiseringsforspørsler. Signering av ArtifactResolve-forespørsel og SingleLogout må også håndteres av tjenesteeier.dersom tjenesteeier bruker Sun Access Manager, OpenSSO eller OpenAM håndteres dette ved å importere en extended metadata fil fra ID-porten. Alternativt må tjenesteeier selv håndtere signering av Artifact resolve og SingleLogout dersom andre produkt benyttes. WantAssertionsSigned="true" vil si at tjenesteeier krever å få Assertion signert. Kryptering vil bli håndtert av ID-porten. 5.1 Krav til nøkler Det anbefales at samme nøkler brukes for kryptering og signering. Krypteringen skal skje med AES med minimum 128 bits nøkler, og signeringsalgoritmen skal være SHA1withRSA eller SHA256withRSA med minimum 1024 bit modulo. 5.2 Protokoller og NameIDFormat I ID-porten vil SingleLogoutService støtte både HTTP-redirect og SOAP. AssertionConsumerService vil kun støtte HTTP-redirect over SOAP. NameIDFormat støtter både persistent og transient. Se Tilslutningsguide mot ID-porten 2.0 for mer detaljer om metadata, og hvilke krav som er satt vedrørende dette. 4
6 Innmelding i ID-portens Circle of Trust Informasjon om hub-en og nodene utveksles i form av XML-filer med metadata, i henhold til SAML standarden. Dette er en toveis kommunikasjon, så tjenesteeier må konfigurere sin egen programvare med fil/filer fra ID-porten, og sende sin egen konfigurasjonsfil til ID-porten. Disse filene inneholder alle detaljene om lokasjonen for SAMLv2 endepunktene, og hvilke bindinger som er tilgjengelig. Et eksempel på en slik metadata-fil finner du i vedlegg1: Eksempel på metadatafil. Filene skal navngis som følger: [EntityID]_sp_[Meta].xml. EntityID er et attributt i rot-elementet EntityDescriptor, og brukes til å identifisere tjenesten som XML filen beskriver. sp indikerer rollen som tjenesteeier (Service Provider, i motsetning til rollen som Identity Provider). Et eksempel på navngivning for NAV (som er en SP): applikasjoner.nav.no_sp_meta.xml. NB! Som nevnt i kapittel 5, så må tjenesteeier som bruker programvaren Sun Access Manager, Sun OpenSSO eller OpenAM også importere en utvidet metadatafil fra ID-porten importeres hos tjenesteeier. Denne inneholder blant annet informasjon om hva ID-porten krever av kryptering og signering. Når metadatafiler er utvekslet vil man gjennom en import av disse bli lagt til i en Circle of Trust som gjør at man er føderert med ID-porten og andre tjenesteleverandører på samme minimum sikkerhetsnivå. 7 Verifisering av føderering Når både ID-porten og tjenesteeier er korrekt konfigurert kan fødereringen testes ved å prøve å aksessere tjenesten med en nettleser. Dette bør videresende brukeren via nettleseren til ID-porten sine websider, hvor brukeren blir spurt om å logge seg inn med et innloggingsalternativ som oppfyller minimumskravene til sikkerhet for den spesifikke eksponerte tjenesten. DIFI har etablert en rutine for verifisering og godkjenning av integrasjon mot ID-porten. Denne finner du på Samarbeidsportalen på https://samarbeidsportalen.difi.no Leverandører av føderasjonsprogramvare som støtter SAML2 kan få sitt produkt verifisert og listet opp som et verifisert produkt på Samarbeidsportalen. Leverandører som ønsker å listes opp med et produkt som ikke allerede er på SAML 2.0 Interoperable product-listen (http://www.projectliberty.org/liberty/liberty_interoperable/interoperable_produ cts) må levere ytterlige dokumentasjon til Difi for testing. 5
8 Migrering fra verifikasjonsmiljø til produksjon Difi krever at tjenester som skal beskyttes av ID-porten må gå gjennom et verifikasjonsløp før tjenesten kan produksjonssettes. Det er derfor nødvendig at tjenesteeier fødererer en testbasert versjon av sin tjeneste med et testmiljø hos Difi som blir referert til som verifikasjonsmiljøet. Her skal det kun benyttes fiktive data, og ikke reelle brukere. Føderering i verifikasjonsmiljøet utføres på samme måte som i produksjon som beskrevet i kapittel 6. Før en tjeneste kan legges til i produksjonsmiljøet må test i verifikasjonsmiljøet være utført, og alle nødvendige avtaler må være signert. 9 Logging Det anbefales at tjenesteeier logger følgende informasjon om forsøk på autentisering: Dato og tidspunkt Hvilken handling som ble forsøkt Resultatet av handlingen Brukerens IP adresse SessionIndex Personnummer SessionIndex er en identifikator som identifiserer bruker-sesjonen på tvers av føderasjonen. ID-porten logger mer detaljert informasjon om hver bruker-sesjon enn det som er påkrevd av tjenesteeier, og tjenesteeier kan be om tilgang til denne med referanse til SessionIndex. Et eksempel på en SessionIndex er s295ce0f891244bf4a68e468368aaa923ead5f4301. 10 Tegnsett Alle SAMLv2 kommunikasjon er basert på utveksling av xml baserte meldinger. All SAML kommunikasjon krever derfor UTF-8 tegnsett. 11 Konfigurasjon av sesjon ID-porten sender ikke en forespørsel om utlogging til tjenesteeier når en sesjon timer ut pga total lengde eller inaktivitet. Forespørsel om utlogging sendes bare når en bruker foretar en eksplisitt utlogging (ved å klikke på logout-knappen hos en tjeneste innenfor Circle of Trust). En slik forespørsel om utlogging fra ID-porten MÅ resultere i en utlogging fra tjenesteeier, ellers vil Single Logoutmekanismen bli kompromittert. Se Tilslutningsguide mot ID-porten 2.0 for mer informasjon om konkrete krav til sesjonstider og mer grunnleggende informasjon om dette. 6
12 Caching av SAML meldinger HTTP Proxy servere og agenter må unnlate å cache SAML meldinger. OASIS foreslår følgende retningslinjer: Ved bruk av HTTP 1.1 (RFC2616) bør forespørrende part Inkludere et Cache-Control header felt satt til no-cache, no-store. Inkludere et Pragma header felt satt til no-cache Ved bruk av HTTP 1.1 bør respondenter: Inkludere et Cache-Control header felt satt til no-cache, no-store, mustrevalidate, private. Inkludere et Pragma header felt satt til no-cache IKKE inkludere Validator-felter som Last-Modified eller ETag header. I SAML sammenheng er forespørrende part og respondenter de entiteter som sender og mottar SAML meldinger. Leverandører av programvare som overholder SAMLv2 standarden skal også overholde disse kravene. 13 Tidssynkronisering Bekreftelse på at en bruker er autentisering sendes fra ID-porten til tjenesteeier i form av en SAML-assertion. En assertion inneholder tidsstempel som angir hvor lenge den er gyldig. Det er derfor viktig at alle servere som kommuniserer via SAML har synkroniserte klokker. ID-porten bruker NTP ( network time protocol ) for synkronisering. Det er videre viktig at alle servere i CoT er justert korrekt for tidssone og sommertid. (CET / CEST i Norge). For mer informasjon om NTP, se http://en.wikipedia.org/wiki/network_time_protocol 14 Enkoding av meldinger For HTTP Redirect bindingen, som beskrevet i Tilslutningsguide mot IDporten 2.0 må alle meldinger basert på SAML protokollen enkodes med base64. 15 IP-adresser Tjenesteeiere må rapportere IP-adressen(e) til servere som kontakter ID-portens servere direkte, via SAML SOAP-bindingen. Dette gjelder både for verifikasjonsmiljøet (test) og produksjonsmiljøet. 7
16 Logo til tjenesteeier i ID-porten I forbindlese med at det i ID-porten vil bli vist tjenesteeier sin logo under autentiseringsløpet, trenger Difi også litt informasjon fra tjenesteeier. Under er et eksempel på hvilken informasjon som trengs: ENTITY_ID=eksempel_101 Dette feltet må være lik entityid i metadata-filen. NAME=Norsk data og eksempelforening Dette blir brukt av ID-porten under innlogging og beskriver tjenesteeier til innbyggeren i ulike sammenhenger. URL=http://www.eksempel.no/ Dette er URL til tjenesteeier som benyttes for å rute innbyggeren tilbake til tjenesteeier ved avbryting av innlogging eller feilsituasjoner. Dette gjelder per integrasjon man har med ID-porten, så om man har flere intergrasjoner kan disse ha ulike verdier. Selve logoen må oppfylle følgende krav: Filformat:.png,.jpg eller gif. Størrelse: maksimal høgde 90 pixel og en bredde som ikke bør overskride 135 pixel. Farge: Bakgrunnsfargen på ID-porten er #f3f4f4, så logoen bør enten ha denne bakgrunnsfargen eller eventuelt ha transparent bakgrunn. 8
Vedlegg1: Eksempel på metadatafil <EntityDescriptor xmlns="urn:oasis:names:tc:saml:2.0:metadata" entityid="idporten-sptest5.difi.local"> <SPSSODescriptor AuthnRequestsSigned="true" ID="sad6ab0783dd890c52c2e11922642fc8046b67592" WantAssertionsSigned="true" protocolsupportenumeration="urn:oasis:names:tc:saml:2.0:protocol"> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" /> <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" /> <Reference URI="#sad6ab0783dd890c52c2e11922642fc8046b67592"> <Transforms> <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" /> <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" /> </Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" /> <DigestValue>9MVtYkYRlpPer/Fs45xFAHpNMoY=</DigestValue> </Reference> </SignedInfo> <SignatureValue> asrrk9zxtgbpwuaivwwztmluzpl7+2fqb57kkrk96kdtf5ryoeib5dwcigi8ki4r2duvi+54r37w 79zqMwOzCXelb0fjzTJbxagCz4lGT8TjrBlWHaLdQOl8REzS+xHLIIwuI8iegvkAAZ3X+gq7m04K ycgebof+cvx0xnro44g=</signaturevalue> <KeyInfo> <X509Data> <X509Certificate> MIICDjCCAXcCBEx82i4wDQYJKoZIhvcNAQEFBQAwTjELMAkGA1UEBhMCTk8xDTALBgNVBA otberjrkkxetapbgnvbastceleug9ydgvumr0wgwydvqqdexrpzhbvcnrlbi1zchrlc3qtc2f tbdaefw0xmda4mzexmdmymtrafw0ymda4mjgxmdmymtrame4xczajbgnvbaytak5pmq 0wCwYDVQQKEwRESUZJMREwDwYDVQQLEwhJRFBvcnRlbjEdMBsGA1UEAxMUaWRwb3J0Z W4tc3B0ZXN0LXNhbWwwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJQp2s3/+jrg+cOu1 b8oktbf5t5la8lsifyhm/kov4lfukoxomrn5vhmnzlszzzwqxaa1awn/jfeq/vd4xpqsa3h0ev86a4 i0wjk5fx+hqsgpgeeue5+cw/phsgwgir9n4qw4+x3gewn1srtkcflt82zhkckbc1yvae77pkpxuf AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAgAfah3bG2ZgZPZKBItCXGPEaHcvurYzGzxVlAXzX JG6OiNYo3ZgXzJ2HFNUcloPtLFz9u4NJ5Mw0nEHLuHj8BdQL/UrgXFMrkbIWiKKururDB3tyvpFbdU YfSJO6bexiJDLzHFRUScdqYGhQVBtJ9QSadJrnA5MnLLsWD7uGcbE=</ds:X509Certificate> </X509Data> </KeyInfo> </Signature> <KeyDescriptor use="signing"> <ds:keyinfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:x509data> <ds:x509certificate> MIICDjCCAXcCBEx82i4wDQYJKoZIhvcNAQEFBQAwTjELMAkGA1UEBhMCTk8xDTALBgNVBA otberjrkkxetapbgnvbastceleug9ydgvumr0wgwydvqqdexrpzhbvcnrlbi1zchrlc3qtc2f tbdaefw0xmda4mzexmdmymtrafw0ymda4mjgxmdmymtrame4xczajbgnvbaytak5pmq 0wCwYDVQQKEwRESUZJMREwDwYDVQQLEwhJRFBvcnRlbjEdMBsGA1UEAxMUaWRwb3J0Z W4tc3B0ZXN0LXNhbWwwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJQp2s3/+jrg+cOu1 b8oktbf5t5la8lsifyhm/kov4lfukoxomrn5vhmnzlszzzwqxaa1awn/jfeq/vd4xpqsa3h0ev86a4 i0wjk5fx+hqsgpgeeue5+cw/phsgwgir9n4qw4+x3gewn1srtkcflt82zhkckbc1yvae77pkpxuf AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAgAfah3bG2ZgZPZKBItCXGPEaHcvurYzGzxVlAXzX JG6OiNYo3ZgXzJ2HFNUcloPtLFz9u4NJ5Mw0nEHLuHj8BdQL/UrgXFMrkbIWiKKururDB3tyvpFbdU YfSJO6bexiJDLzHFRUScdqYGhQVBtJ9QSadJrnA5MnLLsWD7uGcbE=</ds:X509Certificate> </ds:x509data> </ds:keyinfo> </KeyDescriptor> <KeyDescriptor use="encryption"> <ds:keyinfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:x509data> <ds:x509certificate> MIICDjCCAXcCBEx82i4wDQYJKoZIhvcNAQEFBQAwTjELMAkGA1UEBhMCTk8xDTALBgNVBA otberjrkkxetapbgnvbastceleug9ydgvumr0wgwydvqqdexrpzhbvcnrlbi1zchrlc3qtc2f tbdaefw0xmda4mzexmdmymtrafw0ymda4mjgxmdmymtrame4xczajbgnvbaytak5pmq 9
0wCwYDVQQKEwRESUZJMREwDwYDVQQLEwhJRFBvcnRlbjEdMBsGA1UEAxMUaWRwb3J0Z W4tc3B0ZXN0LXNhbWwwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJQp2s3/+jrg+cOu1 b8oktbf5t5la8lsifyhm/kov4lfukoxomrn5vhmnzlszzzwqxaa1awn/jfeq/vd4xpqsa3h0ev86a4 i0wjk5fx+hqsgpgeeue5+cw/phsgwgir9n4qw4+x3gewn1srtkcflt82zhkckbc1yvae77pkpxuf AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAgAfah3bG2ZgZPZKBItCXGPEaHcvurYzGzxVlAXzX JG6OiNYo3ZgXzJ2HFNUcloPtLFz9u4NJ5Mw0nEHLuHj8BdQL/UrgXFMrkbIWiKKururDB3tyvpFbdU YfSJO6bexiJDLzHFRUScdqYGhQVBtJ9QSadJrnA5MnLLsWD7uGcbE=</ds:X509Certificate> </ds:x509data> </ds:keyinfo> <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"> <xenc:keysize xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"> 128</xenc:KeySize> </EncryptionMethod> </KeyDescriptor> <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://idporten-sptest5.difi.local:8080/opensso/SPSloRedirect/metaAlias/sp" ResponseLocation="http://idporten-sptest5.difi.local:8080/opensso/SPSloRedirect/metaAlias/sp" /> <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://idporten-sptest5.difi.local:8080/opensso/SPSloSoap/metaAlias/sp" /> <ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://idporten-sptest5.difi.local:8080/opensso/SPMniRedirect/metaAlias/sp" ResponseLocation="http://idporten-sptest5.difi.local:8080/opensso/SPMniRedirect/metaAlias/sp" /> <ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://idporten-sptest5.difi.local:8080/opensso/SPMniSoap/metaAlias/sp" ResponseLocation="http://idporten-sptest5.difi.local:8080/opensso/SPMniSoap/metaAlias/sp" /> <NameIDFormat> urn:oasis:names:tc:saml:2.0:nameid-format:persistent</nameidformat> <NameIDFormat> urn:oasis:names:tc:saml:2.0:nameid-format:transient</nameidformat> <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="http://idporten-sptest5.difi.local:8080/opensso/Consumer/metaAlias/sp" index="0" isdefault="true" /> </SPSSODescriptor> </EntityDescriptor> 10