2.7 Attributstyrning SAML
Inledning
SAML attributstyrning innebär att en SP själv kan ange i sitt metadata (i kombination med sitt <AuthnRequest>
) vilka attribut som efterfrågas för alla, eller en specifik autentisering. Detta möjliggör att autentisering av en web-klient kan ske utan att man behöver göra ett uppdragsval, vilket exempelvis är användbart i de fall man bara har krav på identifiering och inte vill ha behörighetsstyrande attribut.
Detta kan uppnås genom att man nyttjar delar som är specificerade inom SAML och kombinerar data i entiteterna <IDPSSODescriptor>
, <SPSSODescriptor>
samt <AuthnRequest>
.
En SP som förväntar sig ta emot attribut via <AttributeStatement>
från IdP:n måste ange 1..* <AttributeConsumingService>
i sitt metadata. Detta ligger till grund för funktionaliteten som beskrivs nedan.
Specifikation enligt SAML v2.0
IDPSSODescriptor (IdP-metadata)
IdP:n specificerar i sitt metadata vilka attribut som den kan leverera. Nedanstående bild beskriver hur IdP-metadatat kan se ut med exempel på olika attribut som IdP:n kan tillhandahålla.
<saml:Attribute Name="urn:sambi:names:attribute:levelOfAssurance" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="levelOfAssurance"/> <saml:Attribute Name="http://sambi.se/attributes/1/employeeHsaId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="employeeHsaId"/> <saml:Attribute Name="http://sambi.se/attributes/1/givenName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="givenName"/> <saml:Attribute Name="http://sambi.se/attributes/1/systemRole" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="systemRole"/> <saml:Attribute Name="http://sambi.se/attributes/1/commissionHsaId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="assignmentHsaId"/>
SPSSODescriptor (SP-metadata)
En SP kan välja att lägga till 1..* <AttributeConsumingService>
i sitt metadata som sub-element till <SPSSODescriptor>
. Dessa kommer sedan via sitt index matchas mot angivet värde i ett <AuthnRequest>
. Baserat på vilka attribut som en SP begär vid ett specifikt autentiseringstillfälle kommer IdP:n avgöra om uppdragsval (eller HSA-uppslag generellt) behöver göras eller ej.
Nedan följer ett gäng exempel som en SP kan ange för att kunna uppnå olika sorters attributuppslag i sin autentisering av användare.
OBS! Notera att nedanstående enbart är exempel! Dvs det är inte dessa specifika attribut som styr om ett uppdragsval skall göras eller ej, utan dessa är enbart exempel.
AttributeConsumingService utan HSA-uppslag
<AttributeConsumingService index="0" isDefault="true"> <ServiceName xml:lang="sv">TestSP utan HSA-uppslag</ServiceName> <RequestedAttribute Name="urn:sambi:names:attribute:levelOfAssurance" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="levelOfAssurance"/> </AttributeConsumingService>
Då denna <AttributeConsumingService>
är satt till default så är det denna som kommer användas om SP:n i sitt <AuthnRequest>
avstår från att ange vilken service som skall användas.
Servicen för detta index innehåller enbart ett attribut som IdP:n skall leverera. Eftersom detta attribut inte kräver något HSA-uppslag kommer IdP:n att autentisera användaren utan att använda HSA-katalogen. Enbart de attribut som efterfrågas kommer tillhandahållas (försöka tillhandahållas).
AttributeConsumingService med HSA-uppslag
<AttributeConsumingService index="1"> <ServiceName xml:lang="sv">TestSP med HSA-uppslag</ServiceName> <RequestedAttribute Name="urn:sambi:names:attribute:levelOfAssurance" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="levelOfAssurance"/> <RequestedAttribute Name="http://sambi.se/attributes/1/givenName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="givenName" isRequired="true"/> <RequestedAttribute Name="http://sambi.se/attributes/1/systemRole" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="systemRole"/> </AttributeConsumingService>
Om denna <AttributeConsumingService>
efterfrågas kommer IdP:n vara tvungen att utföra en HSA-slagning för att ta reda på värden för (åtminstone) "systemRole". Dock kommer inget uppdragsval göras då båda dessa attribut är oavhängiga av ett uppdrag. "givenName" har i detta fall tillägget "isRequired". Detta innebär att SP:n kräver att detta attribut finns med. Om IdP inte kan få fram detta attribut kommer den misslyckas med autentisering.
AttributeConsumingService med uppdragsval
<AttributeConsumingService index="2"> <ServiceName xml:lang="sv">TestSP med uppdragsval</ServiceName> <RequestedAttribute Name="urn:sambi:names:attribute:levelOfAssurance" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="levelOfAssurance"/> <RequestedAttribute Name="http://sambi.se/attributes/1/givenName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="givenName"/> <RequestedAttribute Name="http://sambi.se/attributes/1/systemRole" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="systemRole"/> <RequestedAttribute Name="http://sambi.se/attributes/1/commissionHsaId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="assignmentHsaId"/> </AttributeConsumingService>
I denna <AttributeConsumingService>
begär SP:n attribut som enbart kan tillhandahållas då IdP:n ber aktören om ett uppdragsval. IdP:n kommer att göra sitt bästa för att tillhandahålla de attribut som SP:n begär, men då inget av attributen är angivna som "isRequired" så kommer autentisering lyckas, oavsett hur många attribut som SP:n får tillbaka. Det är senare upp till SP:n att avgöra vad man vill göra med biljetten.
AttributeConsumingService med samtliga uppdragsval
<AttributeConsumingService index="3"> <ServiceName xml:lang="sv">TestSP med samtliga uppdragsval</ServiceName> <RequestedAttribute Name="urn:allCommissions" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="allCommissions"/> </AttributeConsumingService>
Om man vill undvika uppdragsval i de fall som en användare har flera uppdrag och man vill ha all uppdragsinformation så kan man begära attributet allCommissions som i denna <AttributeConsumingService>
. Detta kan vara användbart i situationer då SP:n vill ha användarens fullständiga behörighet. Detta kommer leda till att IdP:n gör en slagning mot HSA för att hämta samtliga uppdragsval för användaren. Däremot kommer IdP:n i detta scenario inte be användaren göra något uppdragsval. Samtliga uppdragsval kommer skickas tillbaka i biljetten.
AttributeConsumingService med samtliga uppdragsval med val i IdP:n
<AttributeConsumingService index="4"> <ServiceName xml:lang="sv">TestSP med samtliga uppdragsval och uppdragsval i IdP:n</ServiceName> <RequestedAttribute Name="urn:allCommissions" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="allCommissions"/> <RequestedAttribute Name="http://sambi.se/attributes/1/commissionHsaId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="assignmentHsaId"/> </AttributeConsumingService>
I denna <AttributeConsumingService>
begär SP:n attributen allCommissions och assignmentHsaId. I detta fall kommer IdP:n precis som ovan hämta samtliga uppdragsval från HSA och returnera dessa i biljetten. Dock så kommer användaren i det här fallet ändå behöva göra ett uppdragsval i IdP:n för att IdP:n ska kunna returnera ett värde för assignmentHsaId.
AttributeConsumingService med samtliga HSA ID:n
<AttributeConsumingService index="5"> <ServiceName xml:lang="sv">TestSP med samtliga HSA ID:n för användaren</ServiceName> <RequestedAttribute Name="urn:allEmployeeHsaIds" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="allEmployeeHsaIds"/> </AttributeConsumingService>
Om man vill undvika uppdragsval i de fall som en användare har flera HSA ID:n och/eller flera uppdrag och man bara vill ha ett HSA ID:n kan man begära attributet allEmployeeHsaIds som visas i denna <AttributeConsumingService>
. Då returneras en lista av HSA ID:n och SP:n kan då välja ett av dessa, t.ex. via en användardialog.
Utan AttributeConsumingService (ADFS-metadata)
IdP:n stödjer även metadata där ingen <AttributeConsumingService>
finns med. Dessa fall borde uteslutande vara när ADFS-metadata tillhandahålls för anslutning mot Ineras IdP. I dessa fall kan det anslutande systemet fortfarande begära attribut från IdP:n. Vid anslutningen måste en lista av attribut anges som det anslutande systemet vill ha i varje biljett efter lyckad autentisering. Det är denna lista av attribut som IdP:n alltid kommer försöka lösa in. I stunden då autentiseringen utförs finns alltså ingen möjlighet att begära ett annat set av attribut än de som finns registrerade hos oss och angivna i förstudien. Listan på attributen kan dock ändras genom att skicka in en ny förstudie.
AuthnRequest
För varje <AuthnRequest>
så anger SP:n vilken av tidigare specificerade <AttributeConsumingService>
som skall användas. Detta gör att en SP kan begära olika beteende för olika autentiseringar. SP:n väljer att ange attributet "AttributeConsumingServiceIndex" som skall kunna matchas mot ett index som finns i dess metadata. Nedan följer fyra exempel.
AuthnRequest utan HSA-uppslag
<samlp:AuthnRequest xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" ForceAuthn="false" IsPassive="false" ProviderName="Sp Example Name" ID="ID850325636986645032969715339748802383986121801227" Version="2.0" IssueInstant="2013-03-21T09:31:17.235Z" Destination="https://auth.dev.inera.test:443/saml/HTTP-Redirect" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" AttributeConsumingServiceIndex="0">
SP:n skickar in att "index=0" skall nyttjas. Detta mappar i våra exempel ovan mot att HSA-uppslag inte kommer göras.
AuthnRequest med HSA-uppslag
<samlp:AuthnRequest xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" ForceAuthn="false" IsPassive="false" ProviderName="Sp Example Name" ID="ID850325636986645032969715339748802383986121801227" Version="2.0" IssueInstant="2013-03-21T09:31:17.235Z" Destination="https://auth.dev.inera.test:443/saml/HTTP-Redirect" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" AttributeConsumingServiceIndex="1">
SP'n skickar in att "index=1" skall nyttjas. Detta mappar i våra exempel ovan mot att HSA-uppslag kommer göras.
AuthnRequest med uppdragsval
<samlp:AuthnRequest xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" ForceAuthn="false" IsPassive="false" ProviderName="Sp Example Name" ID="ID850325636986645032969715339748802383986121801227" Version="2.0" IssueInstant="2013-03-21T09:31:17.235Z" Destination="https://auth.dev.inera.test:443/saml/HTTP-Redirect" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" AttributeConsumingServiceIndex="2">
SP'n skickar in att "index=2" skall nyttjas. Detta mappar i våra exempel ovan mot att uppdragsval kommer krävas.
AuthnRequest utan index
<samlp:AuthnRequest xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" ForceAuthn="false" IsPassive="false" ProviderName="Sp Example Name" ID="ID850325636986645032969715339748802383986121801227" Version="2.0" IssueInstant="2013-03-21T09:31:17.235Z" Destination="https://auth.dev.inera.test:443/saml/HTTP-Redirect" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified">
Här har skickar SP:n inte med något index. I exemplen ovan så leder detta till att "index=0" kommer att användas (dvs utan HSA-uppslag), eftersom "index=0" var satt som default.
Förval av principalen
Som SP finns möjligheten att på förhand ange information om användaren som inloggningen ska slutföras med. Informationen skickas in som Extension i AuthnRequesten och benämns PrincipalSelection. Se dokumentationen hos DIGG över hur PrincipalSelection fungerar och hur det är tänkt att användas. IdP stödjer idag förval av personnummer, tjänste-id, medarbetaruppdrags-id, organisationsnummer eller orgAffiliation. Dessa värden kan användas enskilt men också kombineras med varandra. IdP ser de tillhandahållna uppgifter som tvingande uppgifter som måste uppfyllas för att slutföra inloggningen. Vidare så gäller att ifall flera av dessa principal-fält specifierats måste samtliga uppfyllas, det räcker alltså inte ifall bara något eller några av principal-värden matchar. Skulle det visa sig att användarens uppgifter inte stämmer överens med det som skickats via PrincipalSelection kommer inloggningen markeras som misslyckad.
Under filtreringen försöker IdP:n göra ett val automatiskt baserad på den informationen som tagits emot i den AuthnRequest som skickats in. Om det är möjligt kan alltså exempelvis ett specifikt tjänste-id pekas ut och användaren slipper göra ett aktivt val i IdP:n. Om den angivna informationen inte är tillräckligt precis för att göra ett automatiskt val kommer användaren presenteras med tjänste-id eller medarbetaruppdragsväljaren i IdP:ns GUI. I väljaren presenteras endast alterantiven som på förhand har filtrerats med hjälp av de inskickade värden i PrincipalSelection.
Attribut som används i syfte att kunna förvälja principalen ändrar inte beteendet även om attributet har isRequired-flaggan specifierat i SP:ns SAML metadata. Detta för att förenkla logiken och få ett konsistent beteende för hur förvalet fungerar. Oavsett om "true" eller "false" återfinns i isRequred-flaggan kommer inloggningen misslyckas om inte IdP hittar matchande uppgifter om identiteten eller medarbetaruppdragen.
Värt att notera är att attributen som kan skickas in via PrincipalSelection inte måste återfinnas bland de begärda attributen i det inlästa SAML metadatat för SP:n. Denna lösa koppling möjliggör således att en SP kan styra förvalet av principalen utan att samtidigt också begära dessa attribut i den resulterande SAML-biljetten. Ett sådant exempel skulle kunna se ut som följer: SP:ns metadata specifierar att man begär attributet commissionName och commissionPurpose. SP:n väljer att göra ett förval av principalen genom att skicka in ett organisationsnummer i PrincipalSelection. Den resulterande SAML-biljetten innehåller commissionName och commissionPurpose, där medarbetaruppdraget som dessa uppgifter kommer ifrån tillhör det inskickade organisationsnumret.
Notera även att filtrering på organisation (orgAffiliation, organizationIdentifier) endast kan leda till en lyckad inloggning om användaren i fråga har medarbetaruppdrag konfigurerat på sig. Det är en känd begränsning då uppgifter om organisationstillhörighet endast erhålls via medarbetaruppdrag genom HSA. Som ett exempel så skulle alltså inloggningen misslyckas i fallet då en organisation matas in i förvalet av principalen men användaren saknar medarbetaruppdrag helt och hållet (eller även när inget av medarbetaruppdragen tillhör den inmatade organisationen).
Attribut
De värden som avläses i IdP:n för PrincipalSelection är:
Attribut (psc:MatchValue) | Används för | Format |
---|---|---|
urn:credential:personalIdentityNumber | Validering av personidentifierare | <psc:MatchValue Name="urn:credential:personalIdentityNumber" xmlns:psc="http://id.swedenconnect.se/authn/1.0/principal-selection/ns">personalIdentityNumber</psc:MatchValue> |
http://sambi.se/attributes/1/personalIdentityNumber | Validering av personidentifierare | <psc:MatchValue Name="http://sambi.se/attributes/1/personalIdentityNumber" xmlns:psc="http://id.swedenconnect.se/authn/1.0/principal-selection/ns">personalIdentityNumber</psc:MatchValue> |
http://sambi.se/attributes/1/employeeHsaId | Filtrering av tjänste-id | <psc:MatchValue Name="http://sambi.se/attributes/1/employeeHsaId" xmlns:psc="http://id.swedenconnect.se/authn/1.0/principal-selection/ns">employeeHsaId</psc:MatchValue> |
http://sambi.se/attributes/1/commissionHsaId | Filtrering av medarbetaruppdrag | <psc:MatchValue Name="http://sambi.se/attributes/1/commissionHsaId" xmlns:psc="http://id.swedenconnect.se/authn/1.0/principal-selection/ns">commissionHsaId</psc:MatchValue> |
urn:orgAffiliation | Filtrering av medarbetaruppdrag | <psc:MatchValue Name="urn:orgAffiliation" xmlns:psc="http://id.swedenconnect.se/authn/1.0/principal-selection/ns">employeeHsaId@organizationIdentifier</psc:MatchValue> |
http://sambi.se/attributes/1/organizationIdentifier | Filtrering av medarbetaruppdrag | <psc:MatchValue Name="http://sambi.se/attributes/1/organizationIdentifier" xmlns:psc="http://id.swedenconnect.se/authn/1.0/principal-selection/ns">organizationIdentifier</psc:MatchValue> |
Övriga attribut kommer att ignoreras. Attributet SAML Subject kan användas för att förmedla personidentifierare med samma påföljder som om PrincipalSelection används. Endast ETT sätt ska användas för att förmedla Personidentifierare. Endast ETT sätt ska användas för att förmedla tjänste-id och organisationsidentifierare.
Exempel på användningsfall
Låt oss anta att användaren har en uppsättning i HSA som grovt förenklat ser ut som strukturen nedan. Vi antar också att användaren använder sitt eget SITHS eID med personnummret som finns speficierat nedan.
För att hålla exemplen enkla används enbart employeeHsaId, commissionHsaId och personalIdentityNumber som de attribut som begärs via SP:ns SAML metadata. Kom ihåg att som tidigare beskrivet så finns det ingen koppling mellan attributen från SAML metadata och attributen som matas in via PrincipalSelection. Exemplen i tabellen är bara ett litet urval av möjliga scenarion och täcker inte alla användningsfall eller kombinationer.
- Person: 19121212-1212
- Tjänste-id: employeeHsaId 111
- Medarbetaruppdrag: commissionHsaId aaa, organisationsnummer 12345
- Medarbetaruppdrag: commissionHsaId bbb, organisationsnummer 12345
- Tjänste-id: employeeHsaId 222
- Medarbetaruppdrag: commissionHsaId ccc, organisationsnummer 12345
- Tjänste-id: employeeHsaId 333
- Medarbetaruppdrag: commissionHsaId ddd, organisationsnummer 67890
- Tjänste-id: employeeHsaId 444 (saknar medarbetaruppdrag)
- Tjänste-id: employeeHsaId 111
Förval av principalen i praktiken
I exemplet nedan förväntas användaren bli inloggad med personnummer 194211196979, tjänste-id:t TSTNMT2321000156-10NG för organisationen med organisationsnumret 232100-0214.
<saml2p:AuthnRequest xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" Destination="https://idp.dev.inera.test:8443/saml/sso/HTTP-POST" ForceAuthn="false" ID="a4c722ff-4a14-4719-9c11-a36a47c00139" IsPassive="false" IssueInstant="2023-10-19T08:50:52.279Z" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Version="2.0"> <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">https://sp.dev.inera.test:8881</saml2:Issuer> <saml2p:Extensions> <psc:PrincipalSelection xmlns:psc="http://id.swedenconnect.se/authn/1.0/principal-selection/ns"> <psc:MatchValue Name="http://sambi.se/attributes/1/personalIdentityNumber" xmlns:psc="http://id.swedenconnect.se/authn/1.0/principal-selection/ns">194211196979</psc:MatchValue> <psc:MatchValue Name="urn:orgAffiliation" xmlns:psc="http://id.swedenconnect.se/authn/1.0/principal-selection/ns">SE2321000040-4C08@2321000040</psc:MatchValue> </psc:PrincipalSelection> </saml2p:Extensions> </saml2p:AuthnRequest>
Publik Information