1.0.4 - Lokal IdP
Revisionshistorik
Version | Datum | Aktör | Kommentar |
---|---|---|---|
0.1 |
| Upprättad | |
0.2 |
| Former user (Deleted) | Information om konfiguration vid första uppstart |
0.3 |
| Information om hur man skapar Mongodatabas och användare | |
0.4 |
| Former user (Deleted) | Information om mTLS konfiguration och första uppstart |
1.0 |
| Former user (Deleted) | Fastställd för v.1.0.0 |
1.1 |
| Former user (Deleted) | Exempel på routes i lastbalanserare |
1.2 |
| Former user (Deleted) | Information om HSA-anslutning |
1.3 |
| Former user (Deleted) | Omstrukturering. Första version av en checklista. |
1.4 |
| Uppdaterad för v.1.0.4. |
Inledning
Nytt i denna versionen
Ändringar sedan senaste lokala versionen (1.0.2):
Ändringar i 1.0.3
- SAML LogoutResponse saknade <Destination>.
- SAML-specifikationen kräver att <Destination> sätts på Response-meddelanden som skickas via HTTP-Redirect eller HTTP-POST.
- Felet är åtgärdat och <Destination> sätts nu på alla Response-meddelanden som går via HTTP-Redirect och HTTP-POST.
- IdP gick ner om Quartz-schemaläggaren tappade kontakt med MongoDB
- Problemet orsakades av ett tredjeparts-bibliotek för jobb-schemaläggning med quartz. Biblioteket stänger ner hela JVM:en om den stöter på problem, för att undvika risken att ett jobb körs av flera noder.
- Det enda quartz-jobbet som används av IdP är det schemalagda jobbet för att hämta federerat Sambi-metadata.
- Felhanteringen i quartz-biblioteket har ersatts med en no-op hantering.
- Detta får som följdeffekt att om MongoDB-anslutningen bryts så finns det en risk för att flera noder kör samma jobb. I praktiken kan alltså flera noder sätta igång och hämta Sambi-metadata samtidigt.
- Quartz-modulerna i IdP-noderna återupprättar inte anslutning till MongoDB, vilket innebär att om MongoDB-anslutningen bryts så fungerar inte hämtningen av Sambi-metadata längre efter det. (Åtgärdat i v.1.0.4)
Ändringar i 1.0.4
- Bättre felhantering i quartz-modulerna (se ändring #2 i version 1.0.3 ovan).
- Quartz-modulerna återupprättar nu anslutning till MongoDB när databasen finns tillgänglig igen.
- Bättre möjligheter att konfigurera HSA-anslutningen
- Möjlighet att stänga av anrop mot GetAdminCredentialsForPersonIncludingProtectedPerson ifall den anslutna attributkällan inte stödjer det kontraktet.
Stängs av med:
idp.hsa.enable-admin-credentials=false
- Innebär att administrativa uppdrag inte går att hämta.
- Möjlighet att konfigurera parametrar i SOAP-anropen mot HSA
searchBase:
inera.common.hsa.default-search-base=c=SE
LogicalAddress:
inera.common.hsa.logical-adress=SE165565594230-1000
profile:
idp.hsa.profile=extended1
- Möjlighet att stänga av anrop mot GetAdminCredentialsForPersonIncludingProtectedPerson ifall den anslutna attributkällan inte stödjer det kontraktet.
- Rättade en bugg där IdP inte kunde hämta AttributeConsumingService från SP-metadata om SP angav önskat service-index i sitt AuthnRequest men index i metadata inte började på 0.
- Rättade en bugg där logout requests i OIDC som saknade id_token_hint resulterade i en NullPointerException.
- Det går nu att logga ut korrekt även utan en id_token_hint.
- Däremot så krävs att en id_token_hint skickas med för att IdP skall kunna göra en redirect tillbaka till SP. Dokumentationen (OIDC-Profil) uppdaterad.
- Om logout requests i OIDC inte resulterar i en redirect tillbaka till SP så visas istället en sida med utloggningsbekräftelse hos IdP.
- Det gick att få SSO mot IdP även efter utloggning och urdraget kort, så länge browsern fortfarande var öppen, p.g.a. att mTLS-sessionen fortfarande var aktiv (sessionen där IdP fick certifikatet från SITHS-kortet).
- IdP invaliderar nu mTLS-sessionen efter lyckad autentisering.
- Städade bort onödiga attribut i OIDC ID Token
- IdP lägger inte längre till jti-attributet i ID Token
- IdP lägger inte längre alltid till sig själv i audience i ID Token
- I klientregistreringen av OIDC-klienter i Admin-gui så trimmas nu strängar i input-fälten till att ta bort onödiga blanksteg i början och slutet på strängen.
- Avsaknaden av trimning ledde bland annat till att Redirect URI:er som klistrades in kunde ha extra blanksteg i slutet, vilket ledde till felaktigt beteende.
- Rättade en bugg där användare inte fick några attribut alls om de saknade uppdrag i HSA
- Thumbprints för IdP:s certifikat inkluderas inte längre i det publika jwk-settet
- Något tydligare felhantering om användaren kommer in mot en IdP-endpoint utan att ha rätt state.
Checklista inför driftsättning av lokal IdP
En delmängd av de saker som behöver göras inför driftsättning av lokal IdP:
- Teckna användaravtal med Inera för åtkomst att ladda ner applikationen
- Teckna också supportavtal med Inera ifall så önskas
- Påbörja anslutningsförfarandet mot HSA i god tid innan planerad driftsättning av IdP
- Se över klusteruppsättning (egna burkar eller virtuella miljöer)
- Installera/paketera Java 8 med kryptotillägget JCE
- Sätt upp MongoDB med säkerhetskopiering
- Sätt upp Redis
- Sätt upp lastbalanserare
- Se över portöppningar
- Certifikat för åtkomst till HSA, förmodligen ett SITHS-utfärdat funktionscertifikat
- Certifikat för TLS-terminering
- Certifikat för SAML- och OIDC-meddelandesignering och -kryptering
- Fastställ behörighetsregler för administrationsgränssnittet
Plattform och tredjepartsprodukter
Plattform
Lokal IdP levereras som en zip-fil med en filstruktur innehållandes konfigurationsfiler tillsammans med en så kallad "fat jar", d.v.s. en .jar-fil som innehåller applikationen samt webserver och alla applikationens kodberoenden.
Jar-filen kan köras rakt upp och ner på egna servrar, köras i virtuella maskiner eller paketeras i t.ex. en docker-container och hanteras via en container-orkestreringsplattform. Den nationella instansen av Inera IdP paketeras t.ex. i docker-containers baserade på en enkel RHEL-image med Java 8 installerat och driftsätts sedan m.h.a. OpenShift.
Java
Java 8 krävs för att starta applikationen. OpenJDK rekommenderas, men även Oracle JDK/JRE bör fungera (dock bör man vara uppmärksam på att Java Cryptography Extension, JCE, krävs och beroende på version kan behövas installeras separat).
Databaser
IdP:n använder sig av MongoDB och Redis.
Redis-databasen håller enbart temporär lagring (cache, sessioner, et.c.) och behöver således inte säkerhetskopieras.
I MongoDB lagras persistent data (certifikat, klientmetadata, et.c.) och den bör därför säkerhetskopieras regelbundet.
Installation och konfiguration av databaserna ligger utanför scopet för detta dokument.
Följande versioner av databaserna har testats med IdP och kan därför rekommenderas:
Databas | Version |
---|---|
MongoDB | 3.6.3 |
Redis | 4.0.11 |
MongoDB
IdP:n kan ansluta till kluster eller singelnod av MongoDB.
Applikationen kräver att det finns en databas och en användare skapad i MongoDB som den kan använda. För att skapa upp detta, anslut till MongoDB med klienten (mongo/mongo.exe) och ange följande kommandon:
idpdb = db.getSiblingDB("idp") idpdb.createUser({ user: "idpuser", pwd: "idppassword", roles: [ "readWrite" ]}) quit()
Namnet på databasen (idp i exemplet ovan) samt användarnamnet och lösenordet (idpuser och idppassword) kan väljas valfritt, men måste stämma överrens med konfigurationen i application-custom.properties.
IdP:n kommer sedan att vid anslutning automatiskt skapa upp de kollektioner som den behöver.
Redis
Redis används av IdP som en gemensam cache. Alla IdP-noder behöver alltså anslutas till samma uppsättning av Redis.
IdP:n kan ansluta till sentinel (kluster) eller singelnod av Redis. Redis saknar användare, men kan konfigureras för att kräva lösenord för att ansluta. IdP:n har stöd för båda alternativ. Använder man lösenord måste detta konfigureras i application-custom.properties.
Lastbalanserare
IdP:n är tänkt att köras med mer än en instans (klustrad). Det innebär att det behövs en extern lastbalanserare som fördelar lasten mellan noderna.
Routes och TLS-terminering
IdP går upp med två connectorer, en för TLS-trafik (som skall termineras i lastbalanseraren) och en för mTLS-trafik (som skall släppas igenom av lastbalanseraren och termineras i applikationen).
Huvuddomän
Trafik mot IdP:s huvuddomän SSL-termineras i lastbalanseraren.
Certifikat för denna domän installeras alltså i lastbalanseraren.
Subdomän för mTLS
Trafik mot subdomänen secure (typ secure.idp.inera.se, om idp.inera.se är huvuddomänen) skall släppas igenom till applikationen som själv sköter mTLS-termineringen. Nycklar för hantering av mTLS-termineringen läses in i applikationen via admin-gui.
Exempelkonfiguration av routes i LB
Givet följande konfiguration i application-custom.properties:
... idp.server.protocol=https idp.server.host=idp.domain.test idp.server.port=443 ... inera.common.server.mtls.port=8443 ...
så kommer applikationen att innanför lastbalanseraren serva två portar: 8080 (default) samt 8443. Samtidigt är adresserna utåt https://idp.domain.test:443 och https://secure.idp.domain.test:443.
Följande konfiguration skulle då användas i lastbalanseraren:
Inkommande adress | målport hos applikationen | SSL-terminering i LB |
---|---|---|
https://idp.domain.test:443 | 8080 | Ja |
https://secure.idp.domain.test:443 | 8443 | Nej (Passthrough) |
Förslagsvis så redirectas också http-trafik (port 80) till https (port 443).
Headers
Lastbalanseraren måste skicka med följande headers till applikationen:
- X-Forwarded-Proto
- X-Forwarded-Host
- X-Forwarded-Port
- X-Forwarded-For
Certifikat
TLS-trafik
IdP går upp med två connectorer, en för okrypterad trafik (som skall termineras i lastbalanseraren) och en för mTLS-trafik (som skall släppas igenom orört av lastbalanseraren och termineras i applikationen).
- Certifikat och nyckel för IdP:s huvuddomän (ex. idp.domain.test) läses in i lastbalanseraren och används för TLS terminering på all trafik mot huvuddomänen.
- Certifikat och nyckel för subdomänen secure (ex. secure.idp.domain.test om idp.domain.test är huvuddomänen) läses in i applikationen via admin-gui.
Det kan antingen vara två separata certifikat, eller ett wildcard- eller multi-domain-certifikat, t.ex. ett SAN-cert med både huvuddomänen och secure-subdomänen bland sina Subject Alternative Names.
HSA-kommunikation
För kommunikation med HSA-katalogen krävs i regel (och definitivt vid anslutning till den nationella HSA-katalogen) ett SITHS-utfärdat funktionscertifikat vars HSA-id är registrerat i HSA-katalogen som behörigt att anropa aktuella tjänstekontrakt.
Övriga certifikat
Övriga certifikat är de som används för signering av SAML- och OIDC-meddelanden. Vanligtvis är detta också ett SITHS-utfärdat certifikat, och möjligen samma som används för kommunikation med HSA.
Se användarhandboken samt avsnittet om förstagångskonfiguration nedan för mer information kring installation av certifikat och nycklar.
Portöppningar
Applikationen behöver åtkomst till
IP/System |
---|
Mongo databas (samtliga noder) |
Redis databas (samtliga noder) |
HSA |
OCSP/CRL |
SAMBI, ifall federerat metadata skall hämtas |
Beroenden till externa system
HSA
IdP nyttjar HSA som attributkälla, specifikt genom de tjänstekontrakt som finns specificerade i SAD:en.
Anslutning till den nationella HSA-katalogen
Anslutning av en tjänst till den nationella HSA-katalogen föregås av en utförlig anslutningsprocess. Läs mer på https://www.inera.se/tjanster/katalogtjanst-hsa/katalogtjanst-hsa/bestall--andra/ och kontakta Inera för att påbörja ett anslutningsförfarande.
Anslutning till regional HSA-katalog
Anslutning till en lokal/regional HSA-katalog (eller annan tjänst som implementerar de aktuella tjänstekontrakten) hanteras av den lokala/regionala förvaltningen.
Konfiguration av HSA-anslutning
- Certifikat för kommunikation med HSA läses in enligt förstagångs-konfigurationen nedan.
- Vilken HSA-katalog som IdP skall ansluta till konfigureras med följande parametrar i application-custom.properties (se avsnittet om systemkonfiguration nedan):
# HSA WS URL inera.common.hsa.host=https://wstest.hsa.sjunet.org # Paths inera.common.hsa.authorization.getadmincredentialsforpersonincludingprotectedperson=/getadmincredentials_2/hsaws/getadmincredentialsforpersonincludingprotectedperson inera.common.hsa.authorization.getcredentialsforpersonincludingprotectedperson=/tk2/hsaws/getcredentialsforpersonincludingprotectedperson inera.common.hsa.employee.getemployeeincludingprotectedperson=/tk2/hsaws/getemployeeincludingprotectedperson
Applikationskonfiguration
Application properties
Installationsspecifik konfigurering görs i filen config/application-custom.properties. En exempelfil medföljer, men viss konfigurering i denna måste göras innan uppstart.
Framförallt måste idp.server.host, dvs den externa URL som man ansluter till denna instans av IdP:n sättas, samt konfiguration för att ansluta till databaserna (spring.redis.* och spring.data.mongodb.uri) innan uppstart.
Loggning
Inställningar för loggning kan göras i filen logging/logback-spring.xml.
Per default skrivs loggarna till fil (logs/auth-application.log), detta går att ändra till att skrivas till standard out (konsoll) genom att ändra raden <appender-ref ref="FILE" /> till <appender-ref ref="CONSOLE" />.
Inför första uppstart: Konfiguration av nycklar, cert och behörighet
Ställ ner säkerheten på admin-gui och stäng av mTLS-connectorn
När applikationen skall startas första gången så måste säkerheten på administrationsgränssnittet sättas ner för att kunna komma åt admin-gui för att konfigurera nycklar, certifikat och behörigheter.
inera.common.security.web.level=password inera.common.security.web.admin-user.user-name=qwerty inera.common.security.web.admin-user.password=asdfgh
Samtidigt måste mTLS-connectorn vara avstängd tills det finns en nyckelkollektion den kan använda.
inera.common.server.enable=false
Starta sedan applikationen enligt uppstarts-instruktionerna.
Konfigurera systemet via admin-gui
Åtkomst till administrationsgränssnittet sker genom att gå mot /admin-endpointen (t.ex. https://idp.domain.test/admin).
Se användarhandboken för information om hur gränssnittet används.
Konfigurera applikationens certifikat och nycklar
Lägg upp alla nyckelgrupper som behövs och läs in certifikat och nycklar.
Grupp-ID | Beskrivning |
---|---|
idp | Anger de certifikat och nycklar som används av IdP för SAML och OIDC. Det aktiva certifikatet används för signering och övriga certifikat ingår som en del av IdP metadata (inom både SAML och OIDC). |
idp-authentication | Anger de certifikat och nycklar som används av administrationsgränssnittets klient för anslutning mot IdP. |
idp-secure | Anger de certifikat och nycklar som används av mTLS-connectorn på secure-subdomänen för användarautentisering via mTLS. |
hsa | Anger de certifikat och nycklar som används för anslutning till HSA. Är typiskt sett ett SITHS funktionscertifikat vars HSA-id är registrerat i HSA-katalogen som betrott att anropa aktuella tjänstekontrakt. |
Registrera en OIDC-klient för admin-gui
Skapa en OIDC-klient för admin-gui. Kopiera värden från fliken "RP Information" i admin-gui. Dubbelkolla att nyckelgruppen som anges under "RP Information" är skapad enligt ovan.
Konfigurera behörighet för admin-gui
Sätt upp behörighetsregler för vilka HSA-attribut som krävs för att komma åt admin-gui.
- Gå in på "Behörighet"
- Klicka "Ny resurs"
- Fyll i "ADMIN"
- Lägg till en "READ" Action och en "WRITE" Action
- Klicka på respektive action under ADMIN-noden som dyker upp i behörighetsvyn i mitten
- Lägg till önskade Conditions
- Namnsättningen är enligt OIDC-attributen på Attributlistan (t.ex. "employeeHsaId" om ni vill lägga till administratörer en och en, eller "systemRole" och "healthCareProviderHsaId" om alla med en viss roll i en organisation skall ha åtkomst)
- Tillgängliga OIDC-attribut är [ name, employeeHsaId, commissionHsaId, commissionName, healthCareProviderHsaId, organizationName, mail, mobileTelephoneNumber, systemRole ]
- Klicka på respektive Condition och lägg till önskade värden
Läs in betrodda certifikat
Läs in betrodda certifikatsutfärdare för server-2-server kommunikation, användarcertifikat, sambi-federationen och eventuellt övriga metadatautfärdare.
Certifikatsutfärdare för IdP:s egna certifikat måste finnas inlästa för att admin-klienten och IdP skall kunna kommunicera med varandra.
Alla root- och intermediate-certifikat i en certifikatskedja måste finnas inlästa för att ett certifikat skall bli betrott.
Lägg in organisations- och kontaktuppgifter
Under "Konfiguration" i admin-gui: Lägg till organisationsuppgifter samt minst två kontaktpersoner (en av Typ: technical och en av Typ: support). Denna information kommer med i IdP:s SAML-metadata.
Ställ upp säkerheten på admin-gui och aktivera mTLS-connectorn
Säkra admin-gui med OIDC-inloggning
När sedan trust och identiteter satts upp så ställs säkerheten på administrationsgränssnittet upp till att skyddas genom normal inloggning.
inera.common.security.web.level=oidc
Aktivera mTLS-connectorn
Aktivera mTLS-connectorn nu när det finns en nyckelgrupp för den att använda.
inera.common.server.enable=true
Starta om applikationen
Uppstart
Följande är ett exempel på hur applikationen kan startas med nödvändiga JVM-parametrar och environment-variabler.
java -jar \ -Dfile.encoding=UTF-8 \ -Duser.country=SE \ -Duser.language=sv \ -Dspring.profiles.active=custom \ -Xms256m \ -Xmx1024m \ auth-application.jar
IdP-metadata
IdP tillhandahåller SAML- och OIDC-metadata på följande endpoints:
SAML-metadata | OIDC-metadata |
---|---|
<idp url>/saml | <idp url>/oidc/.well-known/openid-configuration |
Administration (GUI)
Inloggning i administrationsgränssnittet sker genom att gå mot /admin (t.ex https://idp.domain.test/admin ).
Se användarhandboken för instruktioner kring hur admin-gui används.
Publik Information