...

Den Gode WebService (DGWS) er en profil for webservices, som bygger på flere WebService standarder fra WS* stakken. Det er ikke en triviel opgave at designe en klient eller en webservice implementering, der overholder DGWS profilen. Seal.Net Api'ets formål er, at sænke den tærskel der uvægerligt er forbundet med at udvikle software der overholder Den Gode WebService. Seal.Net indpakker alle DGWS specifikke detaljer og abstraherer alle typer fra XML til objektform. API'et tager sig af validering og signering.
Seal.NET udgives som en NuGet pakke.

Denne guiden er beregnet til it-faglige personer som skal til eller er i gang med at udvikle systemer, der skal benytte sig af Seal.Net. Det anbefales at platformsintroduktionen læses inden denne guide.

Læseren af denne guide forudsættes at have indsigt i .NET, C#, WCF (WSDL), og XML.

Hvis der er brug for support, kan der laves en indberetning til Service desk. Her kan der også indrapporteres fejl og oprette testdata.

Historik

Den Gode WebService er specificeret i tre versioner 1.0, 1.0.1 og 1.1. Ingen af versionerne er bagud- eller forudkompatible og der er tidligere udviklet individuelle API'er til at understøtte disse versioner.
Dette Api understøtter alle nuværende versioner af DGWS i samme implementering for hhv. klient og service.
Der er dog væsentlige designforskelle mellem dette API og tidligere versioner.

...

Relaterede komponenter

Seal.NET target'er .NET Standard 2.0, så den er kompatibel med .NET 5+ og .NET Core, samt .NET Framework projekter.

Migrering til version 5.x.y fra ældre version

5.0.0 skifter target til .NET Standard 2.0, som medførerer API ændringer. Derudover er der lavet forsimplinger og oprydning af API'et.

Generelt

Net samspiller med en række NSP komponenter. Det kan være en god idé at sætte sig ind i disse, før man går i gang med at udvikle systemer, der benytter sig af Seal.Net. Disse komponenter er listet nedenfor, med links til deres egen ”Kom Godt i Gang Guide”.

STS (Security Token Service)

Det kræver autentificering at få adgang til NSP-komponenter. STS fungerer som en fælles komponent, som kan udstede adgangsgivende billetter til andre komponenter, så disse kun kræver simpel verifikation.

Her er et par steder, man kan starte med at læse om STS:

https://www.nspop.dk/display/public/web/STS+-+Guide+til+anvendere

https://www.nspop.dk/display/public/web/STS+-+Guide+til+anvendere#STSGuidetilanvendere-Anvendelse:Medarbejderomveksling

https://www.nspop.dk/display/public/web/STS+-+Guide+til+anvendere%3A+Borgeromvekslinger

https://www.nspop.dk/display/public/web/STS+-+Guide+til+anvendere%3A+Medarbejderomvekslinger

NTS (NSP Test Service)

NTS er et værktøj til verificering af korrektheden af et DGWS SOAP-request. Hvis der opleves problemer med en service, kan et request i stedet blive sendt til NTS, som vil levere et uddybende svar, om hvad der måtte være galt med det pågældende request. NTS tjekker en række egenskaber ved requests, som f.eks. UTF-8 encoding og eksistensen af de obligatoriske DGWS header-elementer. Yderligere information kan findes her.

NGW (NSP GateWay)

NGW er en særlig udgave af den såkaldte SOSI-GW, som har til formål at sørge for at brugeren kun bliver afkrævet koden til sit medarbejdercertifikat én gang, på tværs af systemer. SOSI-GW og NGW–NSP Gateway ”Kom Godt i Gang Guide”’erne forklarer yderligere.

DCC (DeCoupling Component)

DCC’en fungerer som en WebService Gateway hvilket begrænser kravet til klienten, om kendskab til lokationen af den specifikke service. DCC-Afkoblingskomponenten ”Kom Godt i Gang Guide”’en forklarer yderligere.

Systemkrav

Seal.NET target'er .NET Standard 2.0, så den er kompatibel med .NET 5+ og .NET Core, samt .NET Framework projekter.

Migrering til version 5.x.y fra ældre version

5.0.0 skifter target til .NET Standard 2.0, som medførerer API ændringer. Derudover er der lavet forsimplinger og oprydning af API'et.

Generelt

• app.config er erstattet af appsettings.json og bruges kun til at sætte enkelte parametre:

  Code Block
  language

  app.config er erstattet af appsettings.json og bruges kun til at sætte enkelte parametre:

  Code Block
  language js
  {     "CheckTrust": true,     "CheckDate": true,     "CheckCrl": false,     "sosi:dgws.version": "1.0.1",     "sosi:issuer": "TheSOSILibrary",     "credentialVault:alias": "SOSI:ALIAS_SYSTEM" }

  Værdierne her er også default-værdierne, hvis en parameter eller hele appsettings-filen udelades.

  
Førhen var der ikke overensstemmelse mellem hvad standardværdierne var angivet til i dokumentationen og i koden. 
Koden er ændret, så den nu stemmer overens med dokumentationen.

  Generelt for .NET Standard og WCF gælder det, at det der før blev konfigureret i app.config, nu konfigureres i kode.

  Her er et eksempel på en klient, NtsWSProviderClient, der er genereret ud fra en WCF service reference, som konfigureres i kode, frem for gennem app.config:

  Code Block
  language c#
  var binding = new CustomBinding(); binding.Elements.Add(new TextMessageEncodingBindingElement(MessageVersion.Soap11WSAddressingAugust2004, Encoding.UTF8)); binding.Elements.Add(new HttpTransportBindingElement()); var client = new NSTWsProvider.NtsWSProviderClient(binding, new EndpointAddress("https://test1-cnsp.ekstern-test.nspop.dk:8443/nts/service")); client.Endpoint.EndpointBehaviors.Add(new SealEndpointBehavior()); client.Endpoint.EndpointBehaviors.Add(new ViaBehavior(new Uri("http://test1.ekstern-test.nspop.dk:8080/sosigw/proxy/soap-request"))); var dgwsHeader = new Header() { SecurityLevel = 4, SecurityLevelSpecified = true, Linking = new Linking { MessageID = Guid.NewGuid().ToString("D") } }; using (new OperationContextScope(client.InnerChannel)) { // Adding seal-security and dgws-header soap header OperationContext.Current.OutgoingMessageHeaders.Add(IdCardHeader(idCard)); OperationContext.Current.OutgoingMessageHeaders.Add(XmlHeader(dgwsHeader)); // Throws Exception if not succesful. return client.invokeAsync("test"); }

• Der er tilfælde hvor man måske ønsker at konfigurere en clientVia endpointbehavior på en Web Service Reference som man har tilføjet.
Det blev før gjort i app.config, men da denne ikke længere findes, er der lavet en endpointbehavior klasse som hedder 'ViaBehavior'.
Den bruges som alle andre IEndPointBehavior-klasser:

  Code Block
  language c#
  client.Endpoint.EndpointBehaviors.Add(new ViaBehavior(new Uri("<via URI>")));

• Da app.config ikke længere findes, fremgår det nu af metode-signaturen for Sosi2SamlStsClient og Saml2SosiStsClient, hvilke konfigurationsmuligheder der er til kaldene.

• AbstractCrendentialVault, GenericCertStoreCredentialVault og GenericCredentialVault er fjernet.

  Man kan enten give certifikatet direkte til metoder som skal bruge et certifikat, eller læse det ind fra et certificate store med:

  Code Block
  language c#
  new dk.nsi.seal.Vault.ThumbprintCertStoreCredentialVault(certThumbprint).GetSystemCredentials();

  Internt bruger ThumbprintCertStoreCredentialVault X509Store klassen til at loade et certifikatet fra et certificate store.

  Man kan også implementere sin egen klasse til det, ved at arve fra dk.nsi.seal.Vault.ICredentialVault.

  Essentielt er ICredentialVault bare en måde at give et certifikat til en metode.

• SealCard er fjernet, og fuldt erstattet af IdCard. 'ValidTo' og 'ValidFrom' på SealCard hedder 'CreatedDate' og 'ExpiryDate' på IdCard. Desuden findes 'IsValidInTime' på IdCard, som tjekker de to datoer, og returnerer en bool der angiver om de er overholdt.

• DgwsHeader er fjernet, og DgwsMessageHeader er omdøbt til XmlMessageHeader, da den ikke gør noget DGWS specifikt, men tager noget XML og indsætter det som Header content, når den tilføjes til WCF OutgoingMessageHeaders.

  Den laves nu med en static metode 'XmlMessageHeader.XmlHeader', som direkte tager den værdi der før blev givet til DgwsHeader constructor. Se XmlMessageHeader.

• IdCardMessageHeader laves nu med en static constructor IdCardMessageHeader.IdCardHeader.
• SealSigningEndpointBehavior tager nu ClientCredentials direkte i constructor, i stedet for at den specificeres gennem app.config hvor den blev givet til SealSigningEndpointBehavior gennem AddBindingParameters.
• Create-metoder i SOSIFactory er nu static.
• ICredentialVault-argument er fjernet fra 'SignatureUtil.Validate', da den ikke blev brugt til noget.
• SosiFactory.GetCredentialVault er omdøbt til GetCertificate, og returner nu X509Certificate2.
• 'dk.nsi.seal.SealCardMessageHeader' er erstattet af 'dk.nsi.seal.MessageHeaders.IdCardMessageHeader'.

...

using (var stsClient = new Saml2SosiStsClient("sts_OIOSaml2Sosi"))
{
    stsClient.ChannelFactory.Credentials.ClientCertificate.Certificate = Global.StatensSerumInstitutFoces;
    var healthContextAssertion = SealUtilities.MakeHealthContextAssertion(
        "Test Sundhed.dk",
        Global.StatensSerumInstitutFoces.SubjectName.Name,
        "Sygdom.dk", userAuthorizationCode);
    return stsClient.ExchangeAssertion(nemidAssertion, healthContextAssertion, "http://sosi.dk");
}.ExchangeAssertion(nemidAssertion, healthContextAssertion, "http://sosi.dk");
}

Til

Saml2SosiStsClient.ExchangeAssertion(Global.StatensSerumInstitutFoces, new Uri("<URL der før var i app.config>"), nemidAssertion, userAuthorizationCode);

Hvor nemidAssertion er af typen 'OioSamlAssertion' i stedet for 'Saml2Assertion'.


En 'OioSasmlAssertion' kan laves ud fra et XML dokument på følgende måde:Til

Saml2SosiStsClient.ExchangeAssertion(Global.StatensSerumInstitutFoces, new Uri("<URL der før var i app.config>"), nemidAssertion, userAuthorizationCode);

Hvor nemidAssertion er af typen 'OioSamlAssertion' i stedet for 'Saml2Assertion'.

...

var exampleXmlDoc = new XDocument().Root;
var ast = new dk.nsi.seal.Model.OioSamlAssertion(exampleXmlDoc);

// ast gemmer blot på XML så:
ast.XAssertion == exampleXmlDoc // true

Seal.NET API

Overordnet

Seal.NET er designet til at blive brugt med WCF service references, som laves ud fra WSDL filer. I en WSDL beskrives en snitflade til Den Gode Webservice (DGWS), samt skemaer der beskriver de specifikke DGWS klasser. Når der genereres en proxy til hhv. klient eller server, dannes disse klasser på typestærk form i den autogenererede proxy.

Eksempler på genererede klasser er Security, Assertion og Header, som vises længere nede.

En Header indeholder tekniske og logistiske data, der vedrører forsendelse af request. Specifikke detaljer om hvordan en Header laves kan ses i eksempler længere nede. TODO

En Security er det samlende element for sikkerhedsoplysninger i et request, som indeholder informationer om signering, token og kryptering. For at lave en Security, kræver det at man først har et ID-kort.

Seal.Net giver mulighed for at konstruere to forskellige ID-kort, UserIdCard og SystemIdCard, til anvendelse i fagsystemer indenfor sundhedsvæesnet. Disse konstrueres vha. klassen 'SOSIFactory'

var exampleXmlDoc = new XDocument().Root;
var ast = new dk.nsi.seal.Model.OioSamlAssertion(exampleXmlDoc);

// ast gemmer blot på XML så:
ast.XAssertion == exampleXmlDoc // true

Seal.NET API

Overordnet

Seal.NET er designet til at blive brugt med WCF service references, som laves ud fra WSDL filer. I en WSDL beskrives en snitflade til Den Gode Webservice (DGWS), samt skemaer der beskriver de specifikke DGWS klasser. Når der genereres en proxy til hhv. klient eller server, dannes disse klasser på typestærk form i den autogenererede proxy.

Eksempler på genererede klasser er Security, Assertion og Header, som vises længere nede.

Seal.NET indeholder nogle IEndPointBehavior-klasser som kan benyttes af WCF service references.

Klienter

Saml2SosiStsClient

Konverter Konverterer en SAML assertion til et ID kort.

...

Konverterer et ID kort til en SAML assertion,  enten enten via direkte kald til STS eller via SOSI Gateway.

...