Skapa SAML-metadata
Metadata som publiceras i Sweden Connect måste vara korrekt enligt Sweden Connects tekniska ramverk. Här kan du läsa om hur metadata behöver se ut för att den ska godkännas av oss.
Så fungerar det
För att en e-tjänst ska kunna anslutas till Sweden Connect måste den följa kraven på hur SAML-metadata utformas och används. Kraven finns i Sweden Connects tekniska ramverk, som tillsammans med kompletterande regler för Sweden Connect-federationen reglerar hur metadata för en e-tjänst ska byggas upp.
Sweden Connects tekniska ramverk
Länk till annan webbplats.
En e-tjänst (Service Provider) som ansluter till Sweden Connect publicerar sin SAML-metadata så att legitimeringstjänster (Identity Providers) på ett korrekt sätt kan betjäna skickade begäran om legitimering. Den här sidan beskriver hur metadata måste se ut för att godkännas för publicering till Sweden Connects metadatatjänst.
I exemplen nedan används e-tjänsten Test my eID som är en tjänst som erbjuder möjligheten att testa sitt eID (utländska eller nationella) mot legitimeringstjänster inom Sweden Connect-federationen.
Tänk på det här när du skapar metadata
- Validera alltid din metadata med hjälp av Sweden Connects metadatavalidator Länk till annan webbplats..
- Skapa unik metadata för din tjänst. Metadata innehåller bland annat nycklar som är unika för varje SP/IdP. Du kan därför inte kopiera någon annans metadata.
- Att skapa SAML-metadata är ett steg i anslutningen till Sweden Connect. Har du inte genomfört övriga steg för att ansluta till Sweden Connect behöver du även göra detta. Läs mer under Anslut till Sweden Connect.
EntityID
Alla tjänster identifieras inom federationen med ett unikt entityID. Detta entityID skall vara en giltig URI.
Det är rekommenderat att använda olika entityID för en tjänst som förekommer både i test och produktion. Syftet är att underlätta support- och felsökning, samt att undvika onödiga fel.
<md:EntityDescriptor ... entityID="https://qa.test.swedenconnect.se/sp" ...Entitetskategorier
En e-tjänst måste deklarera ett antal så kallade entitetskategorier som har som syfte att göra utfästelser över de krav och egenskaper e-tjänster har kring anslutandet till Sweden Connect.
Test my eID deklarerar följande:
...<mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"> <saml2:Attribute xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Name="http://macedir.org/entity-category" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml2:AttributeValue xsi:type="xsd:string"> http://id.elegnamnden.se/ec/1.0/loa3-pnr <saml2:AttributeValue> <saml2:AttributeValue xsi:type="xsd:string"> http://id.elegnamnden.se/ec/1.0/eidas-naturalperson </saml2:AttributeValue> <saml2:AttributeValue xsi:type="xsd:string"> http://id.elegnamnden.se/st/1.0/public-sector-sp </saml2:AttributeValue> <saml2:AttributeValue <saml2:AttributeValue xsi:type="xsd:string"> http://id.swedenconnect.se/contract/sc/eid-choice-2017 </saml2:AttributeValue> </saml2:Attribute></mdattr:EntityAttributes>...- http://id.elegnamnden.se/ec/1.0/loa3-pnr - Ska deklareras av e-tjänster som nyttjar legitimeringstjänster enligt Valfrihetssystem 2017. Kategorin talar om att e-tjänsten vill legitimera användare enligt tillitsnivå 3 och med leverans av personnummer i intyg.
- http://id.elegnamnden.se/ec/1.0/eidas-naturalperson - Ska deklareras av e-tjänster som legitimerar användare via den svenska eIDAS-noden.
- http://id.elegnamnden.se/st/1.0/public-sector-sp - Indikerar att e-tjänsten är en tjänst för offentlig verksamhet.
Se också Tekniska anslutningsregler för Sweden Connect som går igenom möjliga entitetskategorier.
Tekniska anslutningsregler för Sweden Connect Länk till annan webbplats.
Information för visning i gränssnitt
De legitimeringstjänster som verkar i Sweden Connect använder sig av e-tjänsters metadata för att kunna visa upp namn och logotyp i användargränssnittet då en användare legitimerar sig. Det är därför väldigt viktigt att denna information är korrekt.
Denna information deklareras i metadata-elementet UIInfo enligt nedanstående exempel:
...<md:Extensions> <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"> <mdui:DisplayName xml:lang="sv">Testa ditt eID</mdui:DisplayName> <mdui:DisplayName xml:lang="en">Test your eID</mdui:DisplayName> <mdui:Description xml:lang="sv"> Applikation för att testa ditt eID </mdui:Description> <mdui:Description xml:lang="en"> Application for testing your eID </mdui:Description> <mdui:Logo height="80" width="228"> https://qa.test.swedenconnect.se/images/sc-logo.svg </mdui:Logo> </mdui:UIInfo></md:Extensions>...- DisplayName - Detta är det namn som används av legitimeringstjänsten då den visar upp information för slutanvändaren om e-tjänsten, till exempel "Logga in till E-myndigheten". Denna information skall finnas på svenska (xml:lang="sv") och engelska (xml:lang="en").
- Description - En mer utförlig beskrivning av e-tjänsten. Denna information skall finnas på svenska (xml:lang="sv") och engelska (xml:lang="en").
- Logo - Ett eller flera element som innehåller länkar till e-tjänstens logotyp/er. Följande regler gäller för detta element:
- Bildens dimensioner måste anges i pixlar, till exempel "height="80" width="228".
- Alla länkar till bilder skall vara https, annars kan användaren få en varning via webbläsaren att vissa objekt inte är säkra.
- Det är rekommenderat att logotyper har formatet SVG (vektorbaserat format).
- Logotyper skall kunna visas på en vit bakgrund. Tänk därför på att logotypen inte ska ha vit text eller på annat sätt förutsätta att bakgrunden har en viss färg.
- Logotypen bör vara transparent, det vill säga, den ska inte fylla i en egen bakgrundsfärg.
Nycklar
En e-tjänst måste deklarera det eller de certifikat som används för att signera och kryptera vid SAML-kommunikation. Antingen skall ett certifikat som kan användas för både signering och kryptering anges, eller så anges separata certifikat för signering och kryptering.
Exempel 1: Samma nyckel
Samma nyckel används för signering och kryptering:
<md:KeyDescriptor> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:KeyName>Example key</ds:KeyName> <ds:X509Data> <ds:X509Certificate>MIIE7DCCAtSgA....IRazyQ==</ds:X509Certificate> </ds:X509Data> </ds:KeyInfo></md:KeyDescriptor>Exempel 2: Separata nycklar
Separata nycklar för signering och kryptering:
<md:KeyDescriptor use="signing"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:KeyName>Signing</ds:KeyName> <ds:X509Data> <ds:X509Certificate> MIIE7DC...RazyQ== </ds:X509Certificate> </ds:X509Data> </ds:KeyInfo></md:KeyDescriptor><md:KeyDescriptor use="encryption"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:KeyName>Encryption</ds:KeyName> <ds:X509Data> <ds:X509Certificate> MIIE7D...yEpbQAw== </ds:X509Certificate> </ds:X509Data> </ds:KeyInfo></md:KeyDescriptor>Notera use="signing" respektive use="encryption".
För det/de certifikat som anges gäller följande regler:
- Skall innehålla RSA-nycklar av lägst 2048-bitars nyckellängd.
- Bör inte återanvändas mellan test- och produktionsmiljöer.
Notera att dessa certifikat inte behöver vara utgivna av en betrodd part, utan agerar endast som "nyckelbehållare".
Adresser och säkerhetskonfiguration
Alla meddelanden som skickas mellan parter i Sweden Connect-federationen är signerade. För en e-tjänst innebär detta att en legitimeringsbegäran (AuthnRequest) som skickas från en e-tjänst till en legitimeringstjänst (IdP) skall vara signerad.
En e-tjänst indikerar deklarerar i metadata att den skickar signerade "request" genom att tildela attributet AuthnRequestsSigned värdet true.
...<md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">...Om en e-tjänst dessutom kräver att intyg (assertions) skall vara signerade skall attributet WantAssertionsSigned sättas till true. Notera att responsmeddelandet i vilket intyget levereras alltid kommer vara signerat.
Name identifiers
En e-tjänst skall enligt kapitel 3 av Deployment Profile for the Swedish eID Framework stödja både persistent och transient Name identifiers.
Deployment Profile for the Swedish eID Framework Länk till annan webbplats.
Varje e-tjänst skall därför inkludera följande i sin metadata:
<md:NameIDFormat> urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat><md:NameIDFormat> urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>Adress för SAML-intyg
En e-tjänst måste deklarera den adress, eller de adresser, där e-tjänsten tar emot SAML-intyg.
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://qa.test.swedenconnect.se/saml2/post" index="0" isDefault="true"/>Följande regler gäller för angivna URL:er:
- Endast https-URL:er accepteras.
- Om mer än en URL anges bör den som är "default" markeras med isDefault="true". I annat fall används den med lägst index-attribut (om inget annat sätts i legitimeringsbegäran).
- Samma URL:er får inte användas i test- och produktionsmiljöer samtidigt.
Organisations- och kontaktinformation
En e-tjänst ska inkludera information rörande organisationen för e-tjänsten:
<md:Organization> <md:OrganizationName xml:lang="sv"> Myndigheten för digital förvaltning </md:OrganizationName> <md:OrganizationName xml:lang="en"> Agency for digital government </md:OrganizationName> <md:OrganizationDisplayName xml:lang="sv"> DIGG </md:OrganizationDisplayName> <md:OrganizationDisplayName xml:lang="en"> DIGG </md:OrganizationDisplayName> <md:OrganizationURL xml:lang="sv"> https://www.digg.se </md:OrganizationURL> <md:OrganizationURL xml:lang="en"> https://www.digg.se/about-us </md:OrganizationURL></md:Organization>Följande regler gäller:
- Namnet som anges som OrganizationName ska finnas på svenska och överensstämma med det namn som angavs vid avtalstecknandet för anslutning till Sweden Connect.
- Kapitel 2 i Deployment Profile for the Swedish eID Framework ställer också som krav att OrganizationDisplayName och OrganizationURL tilldelas.
- De adresser som uppges kan bli kontaktade av Digg eller andra parter i federationen gällande tekniska frågor och support
- Adressen bör vara en funktionsbrevlåda
- Adressen technical avser att användas för tekniska frågor kring integrationen och metadata
- Adressen support avser att användas för allmänna frågor, support och rapportering av incidenter
- Inga personuppgifter får förekomma i kontaktinformationen.
Deployment Profile for the Swedish eID Framework Länk till annan webbplats.
En e-tjänst bör inkludera kontaktinformation. Kontaktinformationen bör vara en mailadress till en funktionsbrevlåda som läses regelbundet och inte en personlig mailadress. Kategorin technical avser att användas vid kontakt för tekniska frågor kring integrationen och ärenden om metadata. Kategorin support avser att användas för allmänna frågor, support och rapportering av incidenter. Ett ContactPerson-element ska då innehålla elementet Company samt åtminstone ett EmailAddress och/eller TelephoneNumber-element.
<md:ContactPerson contactType="technical"> <md:Company><span lang="en">Sweden Connect</span></md:Company> <md:EmailAddress>operations@swedenconnect.se</md:EmailAddress></md:ContactPerson><md:ContactPerson contactType="support"> <md:Company><span lang="en">Sweden Connect</span></md:Company> <md:EmailAddress>support@swedenconnect.se</md:EmailAddress></md:ContactPerson>Frågor och svar
Normalt ska metadata genereras av mjukvaran (SP och IdP).
Dock kan det i vissa fall vara bra att ha en förlaga att jämföra med. Vi rekommenderar att du vid behov tittar på den metadata som publicerats för vår test-SP och referens-IdP:
- https://test.swedenconnect.se/sp (test-SP i produktion)
- https://qa.test.swedenconnect.se/sp (test-SP i QA)
- http://qa.test.swedenconnect.se/idp (referens-IdP i QA).
I Tekniskt ramverk för Sweden Connect finns viktiga kommentarer i ändringar och tillägg som gjorts i förhållande till SAML-standarden.
Tekniskt ramverk för Sweden Connect
Länk till annan webbplats.Tänk på att göra följande:
- Skapa unik metadata för din tjänst. Metadata innehåller bland annat nycklar som är unika för varje SP/IdP. Du kan därför inte kopiera någon annans metadata.
- Validera alltid din metadata med hjälp av metadatavalidatorn.
Sweden Connects metadatavalidator
Länk till annan webbplats.
Börja med att vänta lite
När din metadata validerats och signerats tar det upp till 10 minuter innan den ingår i metadataströmmen och ytterligare 10-20 minuter innan alla IdP:er har plockat upp ändringen. Detta gäller även eIDAS-connectorn. Vänta därför med att felanmäla problem i ca 30 minuter för att vara säker på att allt hunnit uppdateras.
Om du begärt att få metadata publicerad i QA eller produktion kan det ta ännu längre tid eftersom det sker manuella kontroller av din tjänst innan metadata godkänns.
I test/utvecklingsmiljön (sandbox.swedenconnect.se) finns det ett självservicegränssnitt. Där bör din metadata dyka upp inom några minuter om den är korrekt formaterad.
Testa din metadata i metadatavalidatorn
För att minska risken för problem ska du alltid använda validatorn för att se till att ditt metadata är korrekt. Validatorn fångar de allra flesta problem vi känner till och om du inte har några fel eller varningar där bör ditt metadata dyka upp inom 10 minuter från att du har fått en bekräftelse på att det blivit mottaget och godkänt för publicering.
Observera att för produktion måste du ha ett giltigt avtal med Sweden Connect för att ditt metadata ska godkännas för publicering.
Observera också att det inte sker någon automatiskt uppdatering av ditt metadata - om du ändrar på något måste du skicka en ny version.
Sweden Connects metadatavalidator
Länk till annan webbplats.
De svarskoder som kan komma från systemet finns listade i avsnitt 3.2.2.2 Element <StatusCode> i dokumentet "Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0" som utgör standarden för SAML2,
Dessutom tillkommer 3 felkoder som beskrivs i avsnitt "6.4 Error responses" i tekniskt ramverk.
Tekniskt ramverk för Sweden Connect
Länk till annan webbplats.
Sannolikt saknas en annonsering av vilka identitetsattribut som önskas av e-tjänsten i dess metadata. Du kan läsa mer i tekniskt ramverk för Sweden Connect, och på sidan Entitetskategorier och tillitsnivåer.
Tekniskt ramverk för Sweden Connect
Länk till annan webbplats.