Release notes

Release 2.0.2

Release 2.0.1

I konfigurationsfilen sosigw-staticconf.properties, skal sts url(er) i property runtimeconfig.general.sts.service.url ikke længere slutte på /SecurityTokenService.
Fx rettes http://test1-cnsp.ekstern-test.nspop.dk:8080/sts/services/SecurityTokenService til http://test1-cnsp.ekstern-test.nspop.dk:8080/sts/services

Release 2.0.0
Flyttet kodebasen til https://svn.nspop.dk/svn/components/sosigw/
Koden bygges med maven i stedet for ant
Koden kan startes i docker setup

Gateway

SOSI Gateway er en cache af aktive id-kort signeret af STS'en, samt en proxy som erstatter usignerede id-kort i forespørgelserne med disse aktive id-kort.

I stedet for at en bruger bliver afkrævet at taste koden til sit medarbejdercertifikat i alle de systemer som vedkommende skal anvende i løbet af dagen, så kan SOSI Gateway tilbyde, at det kun er ved anvendelse af det første system hver dag, at certifikatet skal anvendes. Hvis alle systemerne anvender SOSI Gateway korrekt vil der blive lagt et signeret id-kort i cachen ved første anmodning, og herefter vil dette id-kort blive brugt i alle andre forespørgelser.

Dette sker ved at systemerne sender et usigneret id-kort med en identifikation af brugeren med i alle forespørgelser, SOSI Gateway erstatter dette id-kort med det passende fra cachen. Identifikationen af brugeren sker ved brug af dennes personnummer og betyder at ansvaret for at det korrekte id-kort bliver anvendt flyttes ud til slutsystemerne.

SOSI Gateway er kun ment som en proxy for forespørgelser, der kræver bruger-id-kort signeret med et MOCES certifikat. VOCES og FOCES certifikater kan ikke bruges sammen med SOSI Gateway.

Anvendelse

I dette afsnit findes en kort oversigt over de skridt et system skal tage for at anvende SOSI Gateway. I de følgende hovedafsnit vil hvert skridt i anvendelsen af SOSI Gateway blive gennemgået i detaljer.

Adgang

SOSI Gateway er tilgængelig på alle NSP installationer. På cNSP fungerer SOSI Gateway som Kommunernes Gateway og er sat op foran DCC. På dNSP installationer er SOSI Gateway placeret efter DCC.

Der er i praksis ingen adgangskrav til SOSI Gateway, men det er dog muligt for operatøren at konfigurere en whitelistning i fremtiden.

Explicit login

Første gang en bruger har brug for at tilgå en service på NSP, laver systemet et opslag i SOSI Gateway, for at se om der allerede ligger et aktivt id-kort i cachen. Dette opslag udføres med operationen "getValidIdCard"

Hvis der ikke ligger et aktivt id-kort i cachen bygges der et nyt usigneret id-kort efter reglerne beskrevet i guiden STS - Signering, og dette sendes til SOSI Gateway via operationen "requestIdCardDigestForSigning". Slutbrugerens certifikat og privat nøgle fremfindes og anvendes til at underskrive det digest der blev returneret fra SOSI Gateway. Signaturen sendes nu med operationen "signIdCard". Efter disse operationer er gennemført ligger der et aktivt id-kort signeret af STS'en i SOSI Gateway cachen.

Hvis der allerede ligger et aktivt id-kort i cachen, så kan proxy servicen bruges direkte og slutbrugeren behøves ikke tillade adgang til sin private nøgle, da der ikke skal underskrives et nyt id-kort.

Implicit login

En alternativ måde at anvende SOSI Gateway er ved blot at kalde gennem proxien og så reagere på den DGWSFault fejl der kommer tilbage hvis der ikke fandtes et aktivt id-kort for slutbrugeren. I den fejlbesked der kommer tilbage er der indlejret et svar fra operationen "requestIdCardDigestForSigning" som kan bruges på samme måde som ifm. explicit login. Når operationen "signIdCard" er kaldt kan systemet kalde servicen igennem proxien igen.

Match id-kort

I de fleste kald til SOSI Gateway skal der gives et usigneret id-kort med i SOAP Headeren. Elementet NameId i id-kortet bliver brugt af SOSI Gateway til at identificerer slutbrugeren. Elementet bør indeholde personnummeret for den bruger som anvender systemet. Værdien i elementet bruges som en del af den nøgle som cachen anvender til at matche en slutbruger med vedkomnes id-kort. Det er anvendersystemets ansvar at den værdi der bruges hænger entydigt sammen med den konkrete slutbruger.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:sec="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:xsig="http://www.w3.org/2000/09/xmldsig#" xmlns:secx="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:gw="http://sosi.dk/gw/2007.09.01" xmlns:dgws="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
  <soap:Header>
    <secx:Security>
      <sec:Timestamp>
        <sec:Created>2014-01-30T09:54:15.352+01:00</sec:Created>
      </sec:Timestamp>
      <saml:Assertion id="IDCard">
        <saml:Issuer>Kom Godt i Gang Guider</saml:Issuer>
        <saml:Subject>
          <saml:NameID Format="medcom:cprnumber">1234567890</saml:NameID>
        </saml:Subject>
		...
      </saml:Assertion>
    </secx:Security>
    ...
  </soap:Header>
  ...
</soap:Envelope>

Hvis en bruger har flere autorisationer (og derved kan have flere aktive id-kort) kan det være nødvendigt at anvende en kombineret nøgle til NameId feltet. F.eks. kunne personnummeret og autorisationskoden sammensættes med et punktum. Vær opmærksom på at SOSI Gateway ikke tillader tegnet "#" i nøglen.

Ud over at bruge NameId til identifikation, kan SOSI Gateway være konfigureret til at indele sin cache i partitioner. Denne inddeling anvendes i Kommunernes Gateway.

Identitetsservice

SOSI Gateway fungerer som en cache af id-kort og tilbyder derfor operationer til at få udstedt et id-kort via STS'en. I de følgende underafsnit vil disse operationer blive gennemgået.

Identitetsservicen i SOSI Gateway er tilgængelig på adressen http://<nsp-host>:8080/sosigw/service/sosigw

getValidIdCard

Denne operation finder et id-kort i cachen, der matcher det NameId der findes i SOAP Headeren i forespørgelsen. Hvis der findes et aktivt id-kort returneres dette som en SAML Assertion. En af anvendelsesmulighederne med resultatet af denne operation er at undersøge hvor lang tid der er til et aktivt id-kort udløber. Bemærk at det kun er SAML elementer der returneres, alle XML Signature elementer er fjernet fra resultatet.

requestIdCardDigestForSigning

Denne operation erstatter et eventuelt tidligere id-kort i cachen med det usignerede id-kort i forespørgelsen. Derefter laves en SHA-1 digest af id-kortet som sendes retur til anvenderen.

Ud over en digest sender SOSI Gateway også en URL til en webside hvor en Java Applet kan anvendes til at signere id-kortet. Hvis denne løsning vælges skal anvendersystemet ikke kalde "signIdCard" da dette gøres af Applet'en.

signIdCard

Den digest, som blev dannet af SOSI Gateway ved kaldet til "requestIdCardDigestForSigning", skal dekodes med Base64 og signeres med RSA algoritmen. Signaturen og certifikatet skal herefter enkodes med Base64 og sendes til SOSI Gateway via denne operation.

Det usignerede id-kort i cachen kombineres nu med signaturen og certifikatet og sendes til STS, der ombytter det med et id-kort der er signeret med føderationens certifikat. Dette id-kort lægges nu i cachen og er klar til at blive brugt igennem proxyservicen.

createIdCardFromBST

Anvendes til omveksling af et bootstrap token til et idkort.
Input er en omvekslingsbesked med indlejret bootstraptoken, som viderestilles i uforandret form til SOSI-STS’ens BST2SOSI snitflade.

Det resulterende idkort gemmes i idkort-cachen med det indgående bootstraptokens SubjectNameID som nøgle, medmindre der i det indkommende kald er angivet et ”sosi:SubjectNameID” claim.
I så fald gemmes idkortet under nøglen fra claimet.
Hvis det indgående bootstraptoken er krypteret, skal SubjectNameID være angivet som claim.

Idkortet returneres med alle XML Signature elementer fjernet.

logout

Proxyservice

Proxyservicen i SOSI Gateway fungerer stort set som en helt normal proxy, bortset fra at den udskifter det usignerede id-kort i forespørgelsen med et STS signeret id-kort fra cachen. Følgende underafsnit er en gennemgang af de vigtige detaljer i den behandling af forespørgelsen som proxien foretager, herunder hvordan den endelige webservice identificeres.

Proxyservicen i SOSI Gateway er tilgængelig på adressen http://<nsp-host>:8080/sosigw/proxy/soap-request

Udskiftning af id-kort

Hvis anvenderen ikke ønsker at få udskiftet id-kortet i forespørgelsen kan dette angives med SOAP headeren "PassThrough" i namespacet "http://sosi.dk/gw/2007.09.01". I Kommunernes Gateway er SOSI Gateway konfigureret til at springe udskiftningen over, hvis der findes en signatur i det medsendte id-kort.

Som beskrevet tidligere så vil SOSI Gateway returnere en DGWSFault, hvis der ikke findes et aktivt id-kort i cachen og anvendersystemet kan derefter logge slutbrugeren ind i gatewayen. Det er også muligt at fremtvinge denne opførsel hvis et id-kort har en alder der er større end et specificeret antal minutter. Alderen angives med SOAP headeren "MaxAge" i namespacet "http://sosi.dk/gw/2007.09.01".

Identifikation af webservice

SOSI Gateway anvender et subset af WS-Addressing til at identificere den webservice, der skal kaldes gennem proxien. Følgende elementer fra WS-Addressing læses i SOAP headeren:

• EndpointReference - Dette element er valgfrit, men hvis det medsendes logges indholdet af det.
• To - Dette element er valgfrit i Kommunernes Gateway og obligatorisk i alle andre installationer. Hvis det medsendes bliver forespørgelsen viderstillet til den URL det indeholder. Hvis elementet udelades bliver forespørgelsen istedet sendt videre til DCC, der så afgør, hvilken webservice der skal modtage den endelige forespørgelse. I Kommunernes Gateway skal man være opmærksom på at det kun er muligt at angive lokale services, da andre services skal tilgåes gennem DCC.
• Action - Dette element er valgfrit, men det anbefales at anvender altid medsender det. Hvis det medsendes anvendes teksten heri som værdien for HTTP headeren SOAPAction i forespørgelsen mod webservicen. Hvis elementet udelades anvendes den SOAPAction der blev medsendt som HTTP header i forespørgelsen mod proxien. Hvis elementet ikke medsendes og der ikke er en SOAPAction i HTTP headeren vil kaldet fejle.

Forespørgelse mod webservice

Når SOSI Gateway har identificeret den webservice, som forespørgelsen skal sendes til, sendes forespørgelsen dertil og svaret sendes uændret retur til anvendersystemet.

Eksempler

Til denne guide hører et kodeeksempel der viser hvordan man kan få lagt et id-kort i cachen, og hvordan man kalder gennem proxy servicen. Eksemplerne kan hentes via Subversion på følgende adresse:

• https://svn.nspop.dk/public/guides

Eksemplerne er lavet som et Maven projekt med et fælles modul og et modul for hver guide. Eksemplerne til denne guide ligger i modulet GW og hedder IdCardCacheExample.java. Klasserne er lavet som unittests og kan afvikles direkte i en hvilken som helst IDE der understøtter JUnit 4.

Eksemplerne har indlejret en WSDL fil som anvendes af JAX-WS/JAXB til at generere XML entiteter og service stubbe. Den aktuelle WSDL kan altid hentes på adressen https://wsdl.nspop.dk/sosigw/service/sosigw?wsdl eller sammen med koden på adressen https://svn.nspop.dk/public/components/sosi-gw/latest/code/etc/wsdl/sosigw.wsdl

Testdata

I modulet common ligger et antal Java Keystore filer der hver indeholder et enkelt certifikat. I eksemplerne til denne guide anvendes kun et enkelt af disse certifikater:

IdCardCacheExample

Eksemplerne i denne fil gennemgår de anvendelsesmuligheder som SOSI Gateway stiller til rådighed. Eksemplerne findes i to versioner: en hvor JAX-WS service snitflader anvendes og en hvor JAXB og DOM objekter serialiseres til en streng og sendes som et HTTP requests. Alle metoderne har indlejrede kommentarer som forklarer hvert skridt i eksemplet.

authorizationExampleWithJAXWS og authorizationExampleWithJAXBAndDOM

I disse eksempler lægges der et id-kort i SOSI Gateway cachen. Først bygges et nyt usigneret id-kort med slutbrugerens personnummer som NameId. Dette id-kort sendes med i alle forespørgelser mod SOSI Gateway da NameId identificere slutbrugeren.

explicitProxyExampleWithJAXWS og explicitProxyExampleWithJAXBAndDOM

I disse eksempler lægges der først et id-kort i cachen hvorefter en service på en NSP komponent kaldes. Kaldet til servicen går gennem SOSI Gateway og indeholder et usigneret id-kort med samme NameId som det id-kort der blev lagt i cachen. SOSI Gateway proxy servicen sørger for at bytte det usignerede id-kort ud med et STS signeret id-kort.

implicitProxyExampleWithJAXWS og implicitProxyExampleWithJAXBAndDOM

I disse eksempler kaldes en service direkte gennem SOSI Gateway uden først at logge ind. Den fejl der kommer tilbage anvendes så til at få lagt et id-kort i cachen og servicen kaldes herefter igen.