Indledning

Dette dokument henvender sig til anvendere af Seal.Java. Dette dokument giver en mere overordnet introduktion til Seal.Java. 

I dette dokument beskrives følgendeFormålet med dokumentet er at give en forståelse af STS som produkt:

• Forudsætninger for at kunne anvende Seal.Java
• Hvad kan Anvendelser af Seal.Java anvendes til?
• Kom godt Hvordan kommer man som anvender i gang med at bruge anvende Seal.Java?

Derudover giver dokumentet en oversigt over den funktionalitet Seal.Java understøtter med udgangspunkt i konkrete Java klasser og metoder.

• Oversigt over klasser og metoder.
• Forskelle på Seal.Java 2 og Seal.Java 3.

De forskellige måder Seal.Java kan anvendes på er beskrevet i større detalje i undersider til dette dokument.  I disse undersider indeholder desuden konkrete kodeeksempler for anvendelse af Seal.JavaDer findes desuden nogle underdokumenter til denne side hvor der findes konkrete kodeeksempler på hvordan Seal.Java anvendes.

Forudsætninger

Seal.Java er i modsætning til de øvrige NSP komponenter et kodebibliotek og anvenderne forventes at have andre og mere tekniske forudsætninge.

Man bør som minimum have Et grundlæggende kendskab til følgende er en forudsætning for at kunne anvende Seal.Java:

• Java udvikling 
• XML
• SOAP
SAML
• WS-Security
• X.
509 OCES
• 509
• OCES3
• Sikkerhedsbilletter: Den Gode WebService (DGWS), SAML2 og JSON Webtokens (JWT)

Der vil være en indledende beskrivelse som ikke forudsætter ovenstående.

...

Anvendelser af Seal.Java

...

Seal.Java anvendes til at sikre, at DGWS og IDWS standarden bliver overholdt. Her udbydes en række metoder man kan benytte til at få:

• Bygge requests og responses
• Deserialisering af XML til model objekter
• Serialisering af model objekter til XML
• Signering requests
• Validering af signatur for requests og responses

Når man skal anvende Seal.Java 

...

.

Seal.Java har følgende tre overordnede anvendelser:

1. Som Consumer, hvor den benyttes til at opbygge DGWS/IDWS requests.
2. Som Provider, hvor den benyttes til at modtage DGWS/IDWS requests.
3. Som Security Token Service, hvor den udsteder et token til en Consumer og som Provider stoler på.

De tre måder at anvende Seal.Java på kan illustreres på følgende måde:

Gliffy Diagram
macroId d262981d-9f9d-41ba-a52f-dfae3ba30b31 displayName Seal.Java anvendelser name Seal.Java anvendelser pagePin 3

Kom godt i gang med at anvende Seal.Java

I dette afsnit gennemgås den praktiske fremgangsmåde til at komme i gang med at anvende Seal.Java

...

i en komponent, samt beskrivelse af kodestrukturen.

For at Hvis man vil anvende Seal.Java , så skal man have følgende installeret:

...

er det nødvendigt at have kendskab til de factory-klasser og modelobjekter, der findes i Seal.Java

Der er udarbejdet en vejldning der beskriver hvordan Seal.Java bygges og det er således ikke en del af guide til anvendere: Seal.Java 3 - Guide til udviklere.

Distribution

De binære pakker er tilgængelige igennem NSPOPs Nexus (pakke manager):

https://nexus.nspop.dk/nexus/service/rest/repository/browse/public/dk/sosi/seal/seal/

Her findes også SNAPSHOT udgaver, som kan bruges under udvikling af funktionalitet, der skal testes inden release.

Seal.Java kan anvendesfra en komponent ved at tilføje følgende Maven dependency:

<dependency>
	<groupId>dk.sosi.seal</groupId>
	<artifactId>seal</artifactId>
	<version>3.x.x</version>
</dependency>

Kodestruktur

Modelobjekter

Seal.Java arbejder med XML via W3C Document og eksemplerne i anvenderguiden forudsætter dette. De helt centrale byggeblokke i Seal.Java er en række modelobjekter der afspejler eksempelvis et request, response eller en sikkerhedsbillet (OIO SAML assertion eller ID-kort).

Disse modelobjekter konstrueres vha. af en række model-builder klasser og kaldene til disse er samlet i nogle factory-klasser, så der kun er en enkelt indgang pr. omveksling.

Modelobjekterne bliver signeret som en del af opbygningen.

Ud over metoder til konstruktion af modeobjekter, så indeholder factory-klasserne også indgange til følgende:

• DOM-builders benyttes til at serialisere modelobjekter til XML dokumenter.
• Model-builders benyttes til at deserialisere XML dokumenter til modelobjekter

I det følgende vises et pseudokode-eksempel på hvordan man anvender Seal.Java til at omveksle en borgers Bootstrap token til en NSP IDWS billet.

// Det indkomne XML dokument "stsRequestXmlDocument" er en tekststreng 

// Brug denne factory
OIOSAMLFactory factory = new OIOSAMLFactory();

// Bootstrap token deserialiseres til model objekt
OIOBootstrapToIdentityTokenRequest stsRequest = factory.createOIOBootstrapToIdentityTokenRequestModelBuilder().build(stsRequestXmlDocument);

// SAML Assertion hentes ud
OIOBSTSAMLAssertion assertion = stsRequest.getOIOBSTSAMLAssertion();

// NSP IDWS billetten opbygges ud fra informationerne i SAML Assertion
final CitizenIdentityTokenBuilder identityTokenBuilder = factory.createCitizenIdentityTokenBuilder();

identityTokenBuilder.setSubjectNameID(assertion.getSubjectNameID());
identityTokenBuilder.setSubjectNameIDFormat(assertion.getSubjectNameIDFormat());
identityTokenBuilder.setCprNumberAttribute(assertion.getCpr());
identityTokenBuilder.setHolderOfKeyCertificate(holderOfKeyCertificate);
identityTokenBuilder.setSigningVault(signingVault);
...

// Opbyg samlet response
AbstractOIOToIdentityTokenResponseDOMBuilder<?> responseBuilder = new OIOBootstrapToIdentityTokenResponseDOMBuilder();
responseBuilder.setIdentityToken(identityToken);
responseBuilder.setSigningVault(signingVault);

Document response = responseBuilder.build();

I underdokumenter til anvenderguiden findes der komplette eksempler der vises hele flowet mellem consumer, provider og STS.

Signering

Et andet centralt begreb i Seal.Java er CredentialVault, der benyttes til at afkoble brugen af certifikater og keystores. Dermed er det ikke nødvendigt at have kendskab til den underliggende implementation. Det giver mulighed for at udskifte implementering, f.eks. at bruge Java KeyStore, HSM (Hardware Security Module),  filbaseret vault eller noget andet.

Eksempel på hvordan en CredentialVault opbygges ud fra en PKCS#12-keystore:

CredentialVault signingVault = new ClasspathCredentialVault(null, "Filnavn på PKCS#12 Virksomhedscertifikat", "Kodeord til Virksomhedscertifikat");

...

Oversigt over klasser og metoder

Service Consumer

I den følgende tabel vises en oversigt over de centrale metoder der skal benyttes hvis man anvender omvekslinger Seal.Java som understøtter når kodebiblioteket anvendes af en Service Consumer.

Omvekslingerne er grupperet efter samme farveskema der er anvendt i dokumentationen for NSP Security Token Service. Se STS - Guide til anvendere.

Ud for de enkelte omvekslinger findes et link til en anvenderguider der specifikt handler om denne omveksling. Her findes konkrete kodeeksempler der viser hvordan Seal.Java anvendes for denne omveksling.

Security Token Service

I den følgende tabel vises en oversigt over de centrale metoder der skal benyttes hvis man anvender omvekslinger Seal.Java som understøtter når kodebiblioteket anvendes af en Security Token Service.

Omvekslingerne er grupperet efter samme farveskema der er anvendt i dokumentationen for NSP Security Token Service. Se STS - Guide til anvendere.

Ud for de enkelte omvekslinger findes et link til en anvenderguider der specifikt handler om denne omveksling. Her findes konkrete kodeeksempler der viser hvordan Seal.Java anvendes for denne omveksling.

Service Provider

Service Provider

I den følgende tabel vises en oversigt over de omvekslinger Seal.Java understøtter når kodebiblioteket anvendes af en Service Provider.

Omvekslingerne er grupperet efter samme farveskema der er anvendt i dokumentationen for NSP Security Token Service. Se STS - Guide til anvendere.

Ud for de enkelte omvekslinger findes et link til en anvenderguider der specifikt handler om denne omveksling. Her findes konkrete kodeeksempler der viser hvordan Seal.Java anvendes for denne omveksling.

Forskelle på Seal.Java 2 og Seal.Java 3

Dette afsnit beskriver de funktionelle forskelle på Seal.Java 2.6.x / 2.7.x og Seal.Java 3.0.x.

Seal.Java 3

Den nuværende udgave af Seal.Java er baseret på Java 8 og er afhængig af en række eksterne kodebiblioteker til bla. signering og kryptering i XML. Der findes tilsvarende funktionalitet indbygget som standard i Java 21, så disse ekstern afhængigheder kan fremover undværes.

 Overgang

...

til Seal.Java 3

På følgende punkter er der væsentlige ændringer i forhold til Seal.Java 2:

• Følgende moduler Modulet 'demo' er blevet fjernet:
  
• demo
testtools.
• Methoden SignatureUtil.getSignedInfoBytes() er udgået, da det ikke er understøttet i JDK'en at beregne digest værdier på denne måde.
• Der er ikke længere understøttelse for at repræsentere certifikatet som tekst (isAddCertificateAsReference).