Indledning

Det primære mål for SOSI-biblioteket er at indkapsle det meste af den komplekse logik i SOSI-konceptet bag et meget simpelt API.
Det har været vores mål at konstruere et enkelt indgangspunkt for alle udviklere (en factory-klasse), hvorfra det er muligt at erhverve enkle modelobjekter (POJO's

), der repræsenterer kernekoncepterne i SOSI-skemaet, f.eks. en meddelelse eller et ID-kort.
Når udviklerne har konstrueret disse modelobjekter, er det muligt at "serialisere" dem til XML og vice versa. Deserialisering (fra XML til modelobjekter) udføres også gennem factory-klassen.  Nedenfor vises et meget simpelt flow, hvor en serviceforbruger (f.eks. et medicinsystem) opretter en anmodning, indsætter data i anmodningen, serialiserer den til XML og sender den til en serviceforbruger.

Biblioteker

Standard SOSI-factory

...

Introduktion

Dette dokument beskriver formatet til Healthcare Service User Identification (HSUID) header. HSUID-headeren er designet til at vedligeholde oplysninger om en bruger af sundhedstjenester, uanset om brugeren er borger eller sundhedsfaglig.

Dokument historik

Format af Healthcare Service User Identification Header

Healthcare Service User Identification header består af et HsuidHeader-element, der indeholder en Security Assertion Markup Language-lignende påstand, der i sig selv indeholder et enkelt AttributeStatement-element.

<hsuid:HsuidHeader xmlns:hsuid="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd">
  <hsuid:Assertion IssueInstant=Insert time of call here Version="2.0" id="HSUID">
    <hsuid:Issuer>Mit anvendersystem</hsuid:Issuer>
    <hsuid:AttributeStatement id="HSUIDdata">
      <hsuid:Attribute Name=Insert attribute name here
            NameFormat=Insert possible format here>
        <hsuid:AttributeValue>Insert attribute value here</hsuid:AttributeValue>
      </hsuid:Attribute>
      Insert additional attributes and attribute values here
    </hsuid:AttributeStatement>
  </hsuid:Assertion>
</hsuid:HsuidHeader>

I AttributeStatement findes oplysninger om brugeren som attributter beskrevet nedenfor.

Bemærk, at hvilke og hvor mange forekomster af de enkelte attributter, der er tilladt, afhænger af den specifikke kontekst, hvor HSUID-headeren anvendes.

Attributter i HSUID-headeren

De attributter, der kan og skal bruges i HSUID-header i kald til de enkelte sundhedstjenester, skal specificeres af snitfladebeskrivelsen for tjenesten. Nedenfor er listen over etablerede attributter.

Attributten nsi:UserType

Attributten nsi:UserType angiver, om brugeren er statsborger eller sundhedsprofessionel.

Attributten nsi:ActingUserCivilRegistrationNumber

Attributten nsi:ActingUserCivilRegistrationNumber identificerer brugeren udfra personnummer.

Attributten nsi:OrgUsingID

Attributten nsi:OrgUsingID beskriver identifikationen af den organisation, som en bruger, der er sundhedsfaglig er tilknyttet på brugstidspunktet.

Attributten nsi:ResponsibleUserCivilRegistrationNumber

Attributten nsi:ResponsibleUserCivilRegistrationNumber identificerer den sundhedsfagligeperson under hvis ansvar brugeren handler.

Hvis brugeren handler under en anden sundhedsfagligs ansvar, skal sidstnævnte have en dansk autorisation i sundhedsmyndighedens autorisationsregister. Dette  autorisationsnummer skal angives i attributten nsi: ResponsibleUserAuthorizationCode.

Hvis brugeren ikke handler under en anden sundhedsprofessionals ansvar, skal den samme værdi angives i attributterne nsi: ActingUserCivilRegistrationNumber og nsi:ResponsibleUserCivilRegistrationNumber.

Eksempler på brug er vidst i nedenstående tabel:

Attributten nsi:ResponsibleUserAuthorizationCode

Attributten nsi:ResponsibleUserAuthorizationCode angiver autorisationsnummeret registreret i Sundhedsstyrelsens autorisationsregister for den sundhedsperson, under hvis ansvar brugeren handler.

Hvis brugeren handler under en anden sundhedsfagligs ansvar, skal den anden sundhedsfaglige have et autorisationsnummer registreret i Sundhedsstyrelsens autorisationsregister.

Attributten nsi:ConsentOverride

Attributten nsi:ConsentOverride angiver, om værdispring bruges eller ej. Hvis attributten udelades, betyder det, at værdispring ikke er udført.

Attributten nsi:SystemOwnerName

Attributten nsi:SystemOwnerName angiver navnet på systemejeren af anvendersystemet.

Attributten nsi:SystemName

Attributten nsi:Systemnavn angiver navnet på anvendersystemet

Attributten nsi:SystemVersion

Attrbutten nsi:SystemVersion angiver navnet på anvendersystemet.

Attributten nsi:OrgResponsibleName

Attributen nsi:OrgResponsibleName angiver organisationen ansvarlig for anvendersystemet.

Attributten nsi:CitizenCivilRegistrationNumber

Attributten nsi:CitizenCivilRegistrationNumber angiver CPR-nummer på patient.

Attributten nsi:CitizenUserRelation

Attributten nsi:CitizenCivilUserRelation indikerer forholdet mellem brugeren og patienten. Tilstedeværelsen af denne attribut kræver ikke tilstedeværelsen af attributten nsi:CitizenCivilRegistrationNumber.

Eksempel

Følgende er et eksempel på et HSUID-header for en bruger, der:

• er sundhedspersonale
• har personnummer 2202222222
• er tilknyttet hospitalafdelingen med SHAK-kode 6620151 (svarende til SOR-kode 440081000016006)
• arbejder på vegne af en sundhedsperson med CPR-nummer 1404444444 og autorisationsnummer 12345

<?xml version="1.0" encoding="UTF-8" ?>
<hsuid:HsuidHeader xmlns:hsuid="http://www.nsi.dk/hsuid/2016/08/hsuid-1.1.xsd">
	<hsuid:Assertion IssueInstant="2016-08-24T08:26:17.183Z"
		Version="2.0" id="HSUID">
		<hsuid:Issuer>my-issuer</hsuid:Issuer>
		<hsuid:AttributeStatement id="HSUIDdata">
			<hsuid:Attribute Name="nsi:UserType">
				<hsuid:AttributeValue>nsi:HealthcareProfessional</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:ActingUserCivilRegistrationNumber">
				<hsuid:AttributeValue>2202222222</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:OrgUsingID"
				NameFormat="nsi:sor">
				<hsuid:AttributeValue>440081000016006</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:OrgUsingID"
				NameFormat="nsi:skskode">
				<hsuid:AttributeValue>6620151</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:ResponsibleUserCivilRegistrationNumber">
				<hsuid:AttributeValue>1404444444</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:ResponsibleUserAuthorizationCode">
				<hsuid:AttributeValue>12345</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:SystemOwnerName">
				<hsuid:AttributeValue>Region Midt</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:SystemName">
				<hsuid:AttributeValue>MidtEPJ</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:SystemVersion">
				<hsuid:AttributeValue>9</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:OrgResponsibleName">
				<hsuid:AttributeValue>Driftsafdeling Vest</hsuid:AttributeValue>
			</hsuid:Attribute>
			<hsuid:Attribute Name="nsi:CitizenCivilRegistrationNumber">
				<hsuid:AttributeValue>1212124321</hsuid:AttributeValue>
			</hsuid:Attribute>
		</hsuid:AttributeStatement>
	</hsuid:Assertion>
</hsuid:HsuidHeader>

Fra version 2.6.1 er det muligt at anvende SOSIFacotry uden at bruge en SigntureProvider eller CredentialVault, så længe man ikke bruger funktionalitet der anvender signering. Ved forsøg på at gøre dette får man fejlbeskeden:

You cannot sign an IDCard using a SOSIFactory constructed without SignatureProvider or CredentialVault!

IDWSH-factory

Fra version 2.1 inkluderer Seal.Java nu IDWSHFactory. Version 2.1 markerer begyndelsen af IDWSH-support. Det formodes at fremdidige versioner af Seal.Java vil udvide support og arbejdsgang ved hjælp af IDWSH.
Seal.Java 2.1 understøtter kun IDWSH IdentityToken. Strømmen til konstruktion og anvendelse af IdentityToken er vist nedenstående figur.

Image Removed

OIOSAML-factory

I Seal 2.1.4 blev OIOSAMLFactory introduceret, som giver funktionalitet til at oprette, analysere, underskrive og validere OIOWS-Trust-meddelelser, der bruges ved udveksling af OIOSAML-påstande, der er udstedt af og IdP til SOSI IDCards.

BST2IDWS

Nedenstående er et simplificeret eksempel på hvordan SOSIFactory benyttes til at oprette et bst2idws request med et indlejret OIO2BST bootstraptoken.

BST2SOSI

Oprettelsen af et bst2sosi request er meget i stil med et bst2idws request:

OIOBSTSAMLAssertion-factory

OIOBSTSAMLAssertionFactory benyttes til at oprette OIO bootstraptoken objekter givet et xml element.

Sådanne bootstraptokens kan enten være for medarbejdere (hertil benyttes createOIOBSTSAMLAssertion(...)) eller borgere (hertil benyttes createOIOBSTCitizenSAMLAssertion(...)), og identificeres ud fra deres spec version attribut.

OIOIDWS-factory

Siden Seal 2.5.10 understøttes OIO IDWS.

Eksempel på brug af IDWS hjælpeklasser for service udbydere.

/* Server will setup OIOIDWSFactory */
final Federation federation = new SOSITestFederation(SignatureUtil.setupCryptoProviderForJVM());
final CredentialVault serverTestVault = CredentialVaultTestUtil.getCredentialVaultFromResource(System.getProperties(), "fmk_idws_test.p12");

final OIOIDWSFactory oioidwsFactory = new OIOIDWSFactory(federation, serverTestVault);


// ****************** HANDLING INPUT ******************
// Server side input/request document
SOAPPart soapPart = soapRequestMessage.getSOAPPart();
SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
SOAPBody soapBody = soapRequestMessage.getSOAPBody();
SOAPHeader soapHeader = soapRequestMessage.getSOAPHeader();

/*Parse request document into IDWS request*/
/*Validation is done in parsing. So if any error - no request object is created*/
LibertyRequest request = oioidwsFactory.createRequest(soapEnvelope);

/*Work on request*/
String messageID = request.getMessageID();
assertNotNull(messageID); // Client did not set MessageID - but in cannot be null
String to = request.getTo();
assertEquals("https://myApp", to);

/*Work with CitizenIdentityToken*/
CitizenIdentityToken identityToken = request.getIdentityToken();
assertNotNull(identityToken); // Must be there!
String cpr = identityToken.getCpr();
assertEquals("2512484916", cpr);
BasicPrivileges basicPriviliges = identityToken.getPrivileges();
assertNotNull(basicPriviliges);
/*Work with priviliges*/
Set<String> scopes = basicPriviliges.getScopes();
for (String scope : scopes) {
List<String> privileges = basicPriviliges.getPrivileges(scope);

assertEquals("urn:dk:healthcare:saml:actThroughProcurationBy:cprNumberIdentifier:1111111118", scope);

assertEquals("urn:dk:healthcare:fmk:read", privileges.get(0));
assertEquals("urn:dk:healthcare:fmk:write", privileges.get(1)); 
}

List<String> privilegeList = basicPriviliges.getPrivileges("urn:dk:healthcare:saml:actThroughProcurationBy:cprNumberIdentifier:1111111118");
assertNotNull(privilegeList);
assertEquals(2, privilegeList.size());

/*Work in my app*/
Tag myAppTag = TagUtil.create("http://demo.dk/custom", "myApp","App");
Element myApp = TagUtil.getFirstChildElementNS(soapBody, myAppTag);
String myAppRequestAsString = XmlUtil.node2String(myApp, false, false);
assertEquals("<myApp:App xmlns:myApp=\"http://demo.dk/custom\"><myApp:Field_1>value1</myApp:Field_1><myApp:Field_2 custom_attribute_2=\"value2\"/></myApp:App>", myAppRequestAsString);

Tag myAppHeaderTag = TagUtil.create("http://demo.dk/custom", "myApp","Header");
Element myHeader = TagUtil.getFirstChildElementNS(soapHeader, myAppHeaderTag);
String myAppRequestHeaderAsString = XmlUtil.node2String(myHeader, false, false);
assertEquals("<myApp:Header xmlns:myApp=\"http://demo.dk/custom\">my_app_header</myApp:Header>", myAppRequestHeaderAsString);

// ****************** CREATING OUTPUT ******************
Document outputDocument = XmlUtil.readXml(System.getProperties(), MY_SOAP_APP_REPONSE, false);

/*Sign repsonse with test vault*/
LibertyMessageDOMEnhancer enhancer = oioidwsFactory.createResponseDomEnhancer(outputDocument, true);
enhancer.setWSAddressingAction("myApp.response"); //Required
//enhancer.setWSAddressingMessageID(); //Required - one will be made if not set be server
enhancer.setWSAddressingRelatesTo(request.getTo()); //Required - Validation will fail if not set
//enhancer.setWSAddressingTo("client"); //Optional

enhancer.enhanceAndSign(); // Enhance and sign output document into IDWS valid reponse

/*create response message*/
MessageFactory messageFactory = MessageFactory.newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
soapResponseMessage = messageFactory.createMessage(null, new ByteArrayInputStream(XmlUtil.node2String(outputDocument).getBytes()));
//return responseSoapMessage
//System.out.println(XmlUtil.node2String(responseSoapMessage.getSOAPPart().getEnvelope(), true, false));

Federations

Når SOSIFactory er oprettet, er det let at komme i gang. Overvej følgende kodestykker, der indeholder kode til opbygning af en anmodning (request) som sendes til en tjenesteudbyder (Service provider).

Service Consumer

Properties properties = ...;
SOSITestFederation testFederation = new SOSITestFederation(properties);
CredentialVault credentialVault = ...; // construct or resolve credentialvault here

SOSIFactory factory = new SOSIFactory(testFederation, credentialVault, properties);
Request request = factory.createNewRequest(
		false, // don’t require non-repudiation receipt
		null // Optional flow-ID (not used here)
);

IDCard idCard = ...; // resolve ID-card here

request.setIDCard(idCard);

Element body = ...; // build body DOM element here
request.setBody(body);

Document domDocument = request.serialize2DOMDocument();
String xml = XmlUtil.node2String(domDocument, false, true);
//Send xml to Service provider here

Det reelle arbejde ligger i følgende linier:

Linie 1: Specificering af egenskaber for SOSI, se senere for reference til SOSI-egenskaber
Linie 3: Opbygge/finde instans af Credential Vault.
Linie 11:  Opbygge/finde instans af ID-kort.
Linie 15: Opbygning af indhold til XML
Linie 20: Sende XML til  serviceprovider

Service  Provider

På den "anden side" hos serviceudbyderen bruges biblioteket således. Også her håndterer udvikleren kun ting, der er relateret til forretningsopgaven.

Properties properties = ...;
Federation federation = new SOSIFederation(properties);
CredentialVault credentialVault = ...; // construct or resolve credentialvault here
SOSIFactory factory = new SOSIFactory(federation, credentialVault, properties);

// This implicitely verifies the STS signature on the ID card etc.
Request request = factory.deserializeRequest(xml);

IDCard idCard = request.getIDCard();

// use ID card attributes for authorization here

Element body = request.getBody();

// use information in body for business logic here

Reply reply = factory.createNewReply(
		request,	// dgws version and”In response to” ID
		null 		// Optional flow-ID set to null
);

reply.setIDCard(idCard);

Element replyBody = ...; // build reply body DOM element here
reply.setBody(replyBody);

Document domDocument = reply.serialize2DOMDocument();
String replyXML = XmlUtil.node2String(domDocument, false, true);
// Send replyXML to Service provider here

Konvertering af OCES3-certifikater

OCES3-certifikaterne bruger krypteringsalgoritment AES256 i stedet for 3DES der bruges i OCES2-certifikater. Java 8 understøtter ikke denne krypteringsalgoritme og det er den Java version skal anvendes på NSP.

 Se indholdet af et OCES3-certifikat

Hvis man blot vil se certifikatet, så kan man gøre det vha. OpenSSL og dermed bruge Java 8:

openssl pkcs12 -nodes -in NSTSSnullAnull_Olsen.p12

Indtast nu certifikatets password.

Skift password af et OCES3-cetifikat

Det er muligt at transformere certifikatet fra AES256 til 3DES vha. OpenSSL og man kan samtidig skifte certifikatets password. Det kan gøres i to skridt:

openssl pkcs12 -in NSTSSnullAnull_Olsen.p12 -out NSTSSnullAnull_Olsen.pem -nodes

Indtast nu det medsendte password der blev udleveret sammen med certifikatet.

Indtast nu sidste del af kommandoen:

openssl pkcs12 -export -out NSTSSnullAnull_Olsen-new.p12 -in NSTSSnullAnull_Olsen.pem

Der bliver spurgt om certifikatets nye password - brug f.eks. Test1234.

Det nye certifikat findes i filen NSTSSnullAnull_Olsen-new.p12

Det er nu muligt at se certifikatet med keytool. Eksempel hvor certifikatets password er Test1234:

keytool -v -list -keystore NSTSSnullAnull_Olsen-new.p12 -storepass Test1234

...