1. Inledning

1.1. Nytt i denna versionen

Ändringar sedan senaste lokala versionen (1.0.4):

1.1.1. OIDC

1.1.1.1. at_hash

Attributet "at_hash" tillagt till id_token claims listan. Se Attributlistan.

1.1.2. SAML

1.1.2.1. SOAP binding för SAML LogoutRequest

IDP har nu stöd för ytterligare en SingleLogoutService, denna gång är det SOAP binding som realiserats. LogoutRequest måste vara signerade.

1.1.2.2. Felmeddelanden signeras

IDP signerar nu SAML felmeddelanden.

1.1.2.3. ArtifactResolve meddelanden måste signeras

För att hämta meddelanden via ArtifactResolution endpointen måste request meddelandet signeras.

1.1.2.4. SessionIndex måste anges i utloggningsbegäran

LogoutRequest måste innehålla SessionIndex för att IDP skall kunna terminera tidigare upprättad session. Sessionsindex erhålls i tidigare utfärdad biljett av IDP.

1.1.3. Admininistrationsgränssnittet

1.1.3.1. Rensa federerat metadata

Ny knapp i SAML metadata menyingången för att rensa allt nerladdat federerat metadata.

1.1.3.2. Konfigurera accepterade autentiseringsmetoder per Service Provider / Relying Party

Ny möjlighet finns för att konfigurera vilka autentiseringsmetoder SP/RP accepterar vid autentisering. I nuläget stöds dock bara MTLS.

1.1.3.3. Utöka SAML metadata med interna attribut

Möjlighet finns nu att inaktivera metadata utan att behöva ta bort den.

1.1.3.4. Ny kolumn i SAML metadata menyingången

Kolumnen anger ifall metadatat tillhör en SP eller en IDP.

1.1.3.5. Möjlighet att extrahera certifikat

Under menyingången nyckelhantering går det nu att extrahera certifikatet från den inlästa nyckeln (PKCS12/JKS).

1.1.4. Övrigt

1.1.4.1. SITHS e-id

IDP ger stöd för nya SITHS e-id, se Guide till Inera IdP. Samtidigt tas stödet för Efos utfärdade certifikat bort.

1.1.5. Felrättningar

• Fel i CSV fil till statistiken där innehållet kunde få med sig avskiljare.
• Rättade bugg där logout returnerar state=null om man inte angivit state i utloggningen.
• Rättade bugg där multipla samtidiga anrop mot "authenticate" endpointen i OIDC kunde ge felaktigt state i databasen.

1.2. 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:

1. Teckna användaravtal med Inera för åtkomst att ladda ner applikationen
2. Teckna också supportavtal med Inera ifall så önskas
3. Påbörja anslutningsförfarandet mot HSA i god tid innan planerad driftsättning av IdP
4. Se över klusteruppsättning (egna burkar eller virtuella miljöer)
5. Installera/paketera Java 8 med kryptotillägget JCE
6. Sätt upp MongoDB med säkerhetskopiering
7. Sätt upp Redis
8. Sätt upp lastbalanserare
9. Se över portöppningar
10. Certifikat för åtkomst till HSA, förmodligen ett SITHS-utfärdat funktionscertifikat
11. Certifikat för TLS-terminering
12. Certifikat för SAML- och OIDC-meddelandesignering och -kryptering
13. Fastställ behörighetsregler för administrationsgränssnittet

2. Plattform och tredjepartsprodukter

2.1. 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.

2.1.1. 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).

2.2. 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:

2.2.1. 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.

2.2.2. 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.

2.3. 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.

2.3.1. 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).

2.3.1.1. Huvuddomän

Trafik mot IdP:s huvuddomän SSL-termineras i lastbalanseraren.

Certifikat för denna domän installeras alltså i lastbalanseraren.

2.3.1.2. 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.

2.3.1.3. 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:

Förslagsvis så redirectas också http-trafik (port 80) till https (port 443).

2.3.2. Headers

Lastbalanseraren måste skicka med följande headers till applikationen:

• X-Forwarded-Proto
• X-Forwarded-Host
• X-Forwarded-Port
• X-Forwarded-For

2.4. Certifikat

2.4.1. 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.

2.4.2. 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.

2.4.3. Ö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.

2.5. Portöppningar

Applikationen behöver åtkomst till

3. Beroenden till externa system

3.1. HSA

IdP nyttjar HSA som attributkälla, specifikt genom de tjänstekontrakt som finns specificerade i SAD:en.

3.1.1. 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.

3.1.2. 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.

3.1.3. Konfiguration av HSA-anslutning

1. Certifikat för kommunikation med HSA läses in enligt förstagångs-konfigurationen nedan.
2. 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

4. Applikationskonfiguration

4.1. 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.

############################# IDP CONFIGURATION ##############################


##############################################################################
############################ SERVER CONFIGURATION ############################
##############################################################################
# Outward(!) facing address, should match public address in LB
idp.server.protocol=https
idp.server.host=idp.domain.test
idp.server.port=443

# Actual webserver port
#server.port=8080


##############################################################################
############################### MTLS CONNECTOR ###############################
##############################################################################
inera.common.server.mtls.port=8443

# Disable before first start, until the identity-group (below) has been configured with certificates
inera.common.server.enable=true

# Certificates and keys, configured in the admin GUI
inera.common.server.mtls.identity-group=idp-secure


############################################################################## 
################################## SECURITY ################################## 
##############################################################################  
# Security level for admin GUI
# oidc: Secured with OIDC, default
# password: Secured with formlogin using user/password
# none: Unsecured
inera.common.security.web.level=oidc
 
# Username and password for admin GUI when security level is set to password
inera.common.security.web.admin-user.user-name=qwerty
inera.common.security.web.admin-user.password=asdfgh

# IP ranges allowed to access actuator endpoints
inera.common.security.web.internal-ip-range=127.0.0.1,10.0.0.0/8

# Allow or disallow access with certificates for which OSCP status cannot be verified
inera.common.trust.allow-undetermined=true


##############################################################################
############################# DB CONFIGURATION ###############################
##############################################################################
# Collection prefix
idp.db.prefix=idp


##############################################################################
############################ REDIS CONFIGURATION #############################
##############################################################################
# Password, if any
#spring.redis.password=password

# Connection timeout, ISO8601 Duration format
spring.redis.timeout=PT1M

## Redis single node configuration
#spring.redis.database=0
#spring.redis.password=password
#spring.redis.host=redis-host-url
#spring.redis.port=6379

## Redis sentinel configuration
#spring.redis.sentinel.master=redis-cluster-name
#spring.redis.sentinel.nodes=redis-sentinel-1:26379,redis-sentinel-2:26379,redis-sentinel-3:26379


##############################################################################
########################### MONGODB CONFIGURATION ############################
##############################################################################
## MongoDB single node configuration
#spring.data.mongodb.uri=mongodb://user:password@mongodb:27017/idp


## MongoDB replica set configuration
#spring.data.mongodb.uri=mongodb://user:password@mongodb-node1:27017,mongodb-node2:27017,mongodb-node3:27017,mongodb-node4:27017/didp?replicaSet=mongo-replica-set-name


# QUARTZ (using MongoDB)
spring.quartz.properties.additionalconfig.uri=${spring.data.mongodb.uri}
spring.quartz.properties.additionalconfig.collection-prefix=${idp.db.prefix}_quartz


##############################################################################
#################################### HSA #####################################
##############################################################################
## HSA WS URL
# HSA WS host
inera.common.hsa.host=https://wstest.hsa.sjunet.org

# HSA WS Endpoint 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


## HSA WS Request parameters
#inera.common.hsa.default-search-base=c=SE
#inera.common.hsa.logical-adress=SE165565594230-1000 # (typo will be fixed in future versions.)
#idp.hsa.profile=extended1


## Flag to enable or disable requests to GetAdminCredentialsForPersonIncludingProtectedPerson. 
# Disabling these requests will prevent the use of the AuthorizationScope parameter.
#idp.hsa.enable-admin-credentials=false

##############################################################################
################################# LOG CONFIG #################################
##############################################################################
# External log config, enables updating of log settings in runtime
# If you encounter problems with logging to file while running on MS Windows, use the absolute path to the logconfig file.
logging.config=file:/deployments/logging/logback-spring.xml


##############################################################################
################################### SAMBI ####################################
##############################################################################
# Automated job to fetch federated SAML metadata from SAMBI
saml.sambi-job-enabled=false

# URI to SAMBI federated metadata
saml.federated-metadata-url=https://fed.sambi.se/trial/md/metadata.xml


# Job schedule, default is to fetch once every two hours.
#saml.sambi-job-cron-expression=0 0 0/2 * * ?


##############################################################################
#################################### MISC ####################################
##############################################################################
# Link to the user manual in GUI
idp.usermanual=https://confluence.cgiostersund.se/x/T6yhCg

# Certificate Level of Assurance
# Card serial number pattern for SITHS certificates which should be interpreted as LOA 3.
idp.loa.siths.loa3-pattern=^9752\\d{4}(357|857|957)\\d+$
##############################################################################

4.2. 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" />.

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="60 seconds">
 
  <property name="LOG_FILE" value="logs/auth-application.log" />
  <property name="LOG_FILE_MAX_SIZE" value="10MB" />
  <property name="LOG_FILE_MAX_HISTORY" value="7" />

  <include resource="org/springframework/boot/logging/logback/defaults.xml" />
  <include resource="org/springframework/boot/logging/logback/console-appender.xml" />
  <include resource="org/springframework/boot/logging/logback/file-appender.xml" />
 
  <!-- Global logging level of application -->
  <logger name="com.cgi.se.inera" level="INFO" />
 
  <!-- Supress verbose loggers -->
  <logger name="com.novemberain.quartz.mongodb" level="WARN" />
  <logger name="com.cgi.se.inera.common.pkix.server.X509HeaderFilter" level="WARN" />
  <logger name="com.cgi.se.inera.common.pkix.TrustServiceImpl" level="WARN" />
  <logger name="com.cgi.se.inera.common.job.NonSystemExitMongoDBJobStore" level="WARN" />
 
  <!-- WARNING! -->
  <!-- Enabling message logging can and will expose personal information about end users in the logs! -->
  <!-- Only enable message logging if it is needed for debugging purposes, and only for limited times. -->
 
  <!-- OpenSaml logger for SAML request/response. DEBUG for SAML messages -->
  <logger name="PROTOCOL_MESSAGE" level="INFO" />
   
  <!-- INFO level needed to log the SOAP messages -->
  <logger name="org.apache.cxf" level="WARN" />
  <logger name="org.apache.cxf.services" level="WARN" />
   
  <!-- fine tune individual service logging -->
  <logger name="org.apache.cxf.services.GetEmployeeIncludingProtectedPersonResponderInterface.REQ_OUT" level="WARN" />
  <logger name="org.apache.cxf.services.GetEmployeeIncludingProtectedPersonResponderInterface.RESP_IN" level="WARN" />
  <logger name="org.apache.cxf.services.GetEmployeeIncludingProtectedPersonResponderInterface.FAULT_IN" level="WARN" />
   
  <logger name="org.apache.cxf.services.GetCredentialsForPersonIncludingProtectedPersonResponderInterface.REQ_OUT" level="WARN" />
  <logger name="org.apache.cxf.services.GetCredentialsForPersonIncludingProtectedPersonResponderInterface.RESP_IN" level="WARN" />
  <logger name="org.apache.cxf.services.GetCredentialsForPersonIncludingProtectedPersonResponderInterface.FAULT_IN" level="WARN" />
   
  <logger name="org.apache.cxf.services.GetAdminCredentialsForPersonIncludingProtectedPersonResponderInterface.REQ_OUT" level="WARN" />
  <logger name="org.apache.cxf.services.GetAdminCredentialsForPersonIncludingProtectedPersonResponderInterface.RESP_IN" level="WARN" />
  <logger name="org.apache.cxf.services.GetAdminCredentialsForPersonIncludingProtectedPersonResponderInterface.FAULT_IN" level="WARN" />
 
  <root level="INFO">
    <!-- Log to file or to console -->
    <appender-ref ref="FILE" />
    <!-- <appender-ref ref="CONSOLE" /> -->
  </root>
 
</configuration>

5. Inför första uppstart: Konfiguration av nycklar, cert och behörighet

5.1. 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.

5.2. 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.

5.2.1. Konfigurera applikationens certifikat och nycklar

Lägg upp alla nyckelgrupper som behövs och läs in certifikat och nycklar.

5.2.2. 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.

5.2.3. 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.

1. Gå in på "Behörighet"
2. Klicka "Ny resurs"
3. Fyll i "ADMIN"
4. Lägg till en "READ" Action och en "WRITE" Action
5. Klicka på respektive action under ADMIN-noden som dyker upp i behörighetsvyn i mitten
6. Lägg till önskade Conditions
   1. 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)
   2. Tillgängliga OIDC-attribut är [ name, employeeHsaId, commissionHsaId, commissionName, healthCareProviderHsaId, organizationName, mail, mobileTelephoneNumber, systemRole ]
7. Klicka på respektive Condition och lägg till önskade värden

5.2.4. 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, dock behöver root cert inte vara aktiv i någon kolumn

 Exempelkonfiguration, certifikat

I följande exemplet så använder IdP ett certifikat utfärdat av DigiCert för all verksamhet förutom för kommunikation med HSA-katalogen. DigiCert-certifikatet är inläst på nyckelgrupperna idp, idp-secure och idp-authentication.

För kommunikation med HSA-katalogen använder IdP ett SITHS-utfärdat funktionscertifikat.

Namn	Server	Federation	Användare	Klient	Kommentar
SITHS Root CA v1					Root cert
SITHS Type 1 CA v1					SITHS användarcertifikat
SITHS Type 3 CA v1					HSA Server, IdP certifikat för kommunikation med HSA
DigiCert SHA2 Extended Validation Server CA					IdP
Sectigo RSA Domain Validation Secure Server CA.cer					Sambi Server
sambi-prod					Sambi Metadatasignering

5.2.5. 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.

5.3. Ställ upp säkerheten på admin-gui och aktivera mTLS-connectorn

5.3.1. 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

5.3.2. Aktivera mTLS-connectorn

Aktivera mTLS-connectorn nu när det finns en nyckelgrupp för den att använda.

inera.common.server.enable=true

5.3.3. Starta om applikationen

6. 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

7. IdP-metadata

IdP tillhandahåller SAML- och OIDC-metadata på följande endpoints:

8. 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.