1. Indledning
Denne omveksling kan modtage et NSP OIO SAML Bootstrap Token og returnere et NSP OIO IDWS Identity Token.
Et NSP OIO Bootstrap Token er en SAML 2.0 Assertion der repræsentere en borger. Det udstedes af en Identity Provider (IdP). Det er muligt at opbygge et NSP OIO Bootstrap Token vha. Seal.Java, men det er typisk kun til testformål. Et NSP OIO Bootstrap Token kan valideres ved at kontrollere, at audience svarer til den modtager, det er udstedt til, at gyldighedsperioden ikke er udløbet, og at signaturen er gyldig. Signaturen for en SAML 2.0 Assertion valideres ved at benytte det indlejrede signeringscertifikat.
Det samlede request der sendes til en STS er signeret af en troværdig tredjepart, der enten kan være lokal IdP eller SEB. Det samlede request kan valideres vha. det Holder Of Key certifikat der er indlejret i NSP OIO Bootstrap Token.
Et NSP OIO IDWS Identity Token er en SAML 2.0 Assertion der repræsentere en borger. Det kan opbygges af Seal.Java og det vil typisk være en STS der gør dette i forbindelse med omveksling. Det kan benyttes ved borgerkald af NSP services. Et NSP OIO IDWS Identity Token kan valideres ved at kontrollere, at audience svarer til den modtager, det er udstedt til, at gyldighedsperioden ikke er udløbet, og at signaturen er gyldig. Signaturen for en SAML 2.0 Assertion valideres ved at benytte det indlejrede signeringscertifikat.
I det følgende vises nogle stykker kode der viser hvordan man som anvender skal bruge Seal.Java til denne omveksling.
Der findes et komplet eksempel (incl. STS omveksling) sidst på siden.
2. Eksempel
2.1. Bootstrap Token
2.1.1. Læs OIO SAML Assertion fra IdP
En NSP OIO SAML Assertion der stammer fra en Identity Provider og er repræsenteret i et W3C element kan Seal.Java parse til et OIOBSTSAMLAssertion objekt på følgende måde:
OIOBSTSAMLAssertion oiosamlAssertion = OIOBSTSAMLAssertionFactory.createOIOBSTSAMLAssertion(assertionElement);
Hvor den modtagne OIO SAML Assertion er indlæst i et Element i variablen assertionElement.
2.1.2. Opbyg OIO SAML Assertion
Seal.Java kan anvendes til at opbygge en OIO SAML Assertion. Dette vil typisk ske i forbindelse med test.
Først skal CredentialVaults sættes op og der skal lave en instans af den factory der kan håndtere OIO SAML:
// CredentialVault og Factory CredentialVault signingVault = new ClasspathCredentialVault(null, "Filnavn på PKCS#12 Medarbejdercertifikat", "Kodeord til Medarbejdercertifikat"); CredentialVault holderOfKeyVault = new ClasspathCredentialVault(null, "Filnavn på PKCS#12 Holder of key certifikat", "Kodeord til Holder of key certifikat"); OIOSAMLFactory factory = new OIOSAMLFactory();
En signeret OIO SAML Assertion opbygges vha. Seal.Java på denne måde:
// Byg OIOBSTSAMLAssertion
OIO3BSTSAMLAssertionBuilder oiosamlAssertionBuilder = factory.createOIO3BSTSAMLAssertionBuilder();
oiosamlAssertionBuilder.setIssuer("https://oio3bst-issuer.dk");
oiosamlAssertionBuilder.setNameId("KorsbaekKommune\\MSK");
oiosamlAssertionBuilder.setAudience("http://audience.nspoop.dk/dds");
oiosamlAssertionBuilder.setNotOnOrAfter(notOnOrAfter);
oiosamlAssertionBuilder.setCvr("20301823");
oiosamlAssertionBuilder.setOrganizationName("Korsbæk Kommune");
oiosamlAssertionBuilder.setHolderOfKeyCertificate(holderOfKey.getSystemCredentialPair().getCertificate());
oiosamlAssertionBuilder.setSigningVault(signingVault);
OIOBSTSAMLAssertion oiosamlAssertion = oiosamlAssertionBuilder.build();
2.2. STS Request
2.2.1. Opbygge STS request til testformål
Det samlede STS request med en NSP OIO SAML Assertion opbygges på denne måde:
// NSP OIO SAML Assertion findes i denne variabel:
OIOBSTSAMLAssertion oiosamlAssertion = ...
OIOBSTSAMLAssertionToIDCardRequestDOMBuilder requestBuilder = factory.createOIOBSTSAMLAssertionToIDCardRequestDOMBuilder();
requestBuilder.setAudience("http://audience.nspoop.dk/dds");
requestBuilder.setITSystemName("Korsbæk Kommunes IT systemer");
requestBuilder.setSubjectNameID("Mads_Skjern");
requestBuilder.setSigningVault(signingVault);
requestBuilder.setOIOBSTSAMLAssertion(oiosamlAssertion);
Document consumerStsRequestDocument = requestBuilder.build();
Når requestet sendes over netværket skal det konverteres til XML:
// Konverter til XML så det kan sendes over netværket String consumerStsRequestXml = XmlUtil.node2String(consumerStsRequestDocument, false, false);
Nu vil en STS kunne modtage det og veksle det til en NSP OIO IDWS Identity Token. Eksempel på hvordan Seal.Java kan anvendes til denne omveksling findes her: Seal.Java 3 - Guide til anvendere (STS) - Bootstrap Token til OIO-Idws Token
2.2.2. Request som stream
En consumer vil typisk have et NSP OIO SAML Bootstrap Token som en stream der kan sendes direkte til en STS. Dette vil man selv kunne deserialisere hvis man vil se indholdet:
// Anvender har et XML dokument indeholdende NSP OIO SAML Bootstrap Token request: String consumerStsRequestXml = "<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" ... </soapenv:Envelope>"; Document requestDocument = XmlUtil.readXml(new Properties(), consumerStsRequestXml, false); OIOBootstrapToIdentityTokenRequest request = factory.createOIOBootstrapToIdentityTokenRequestModelBuilder().build(requestDocument);
Det er nu muligt for en STS at se indholdet af requestet og på baggrund af indholdet vil en STS kunne bygge et response.
2.3. STS Response
Når consumeren modtager svaret fra STS, så skal det først indlæses i et W3C Document:
// Konverter XML svaret fra STS til Document Document consumerStsResponseDocument = XmlUtil.readXml(new java.util.Properties(), consumerStsResponseXml, false);
Man kan nu deserialisere svaret til et OIOBootstrapToIdentityTokenResponse modelobjekt:
// Deserialiser STS svaret til modelobjekt OIOBootstrapToIdentityTokenResponse consumerStsResponse = factory.createOIOBootstrapToIdentityTokenResponseModelBuilder().build(consumerStsResponseDocument);
Her efter kan man hente Identity Token ud og verificere attributterne:
// Hent Identity Token fra STS svar
IdentityToken identityTokenResponse = consumerStsResponse.getIdentityToken();
// Verificer at det er et IDWS token samt at assurance level og audience er som forventet
Assert.assertEquals("DK-SAML-2.0", identityTokenResponse.getSpecVersion());
Assert.assertEquals("3", identityTokenResponse.getAssuranceLevel());
Assert.assertEquals("http://fmk-online.dk", identityTokenResponse.getAudienceRestriction());
2.4. Service Request
Når vi har STS svaret kan service requestet opbygges. Først skal der opbygges et IDWS request med den Body der passer til den service der skal kaldes. Den kan se sådan her ud, hvor Body elementet ikke er udfyldt:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header />
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>
Nu kan man så bruge Seal.Java til at berige dette request med det Identity Token der findes i STS svaret (identityTokenResponse) og signere det:
LibertyRequestDOMEnhancer enhancer = oioidwsFactory.createRequestDOMEnhancer(serviceConsumerRequestDocument); enhancer.setIdentityToken(identityTokenResponse); enhancer.setWSAddressingMessageID(messageIdSupplier.get()); enhancer.setWSAddressingAction(soapAction); enhancer.enhanceAndSign(); String serviceConsumerRequestXml = XmlUtil.node2String(serviceConsumerRequestDocument, false, true);
Det samlede request kommer til at se sådan ud, hvor body delen her er tom:
2.5. Service Response
Seal.Java kan nu benyttes til at validere det samlede response fra servicen. Ved kald til en IDWS service kan man vha. kald til Seal.Java tjekke om svaret indeholder en fejl og evt. fejlbesked og fejlkode.
Eksempel på dette hvor vi antager at vi har svaret som et Document i variablen serviceConsumerResponseDocument:
Federation federation = new SOSITestFederation(new Properties());
OIOBootstrapToIdentityTokenResponse response = new OIOBootstrapToIdentityTokenResponseModelBuilder().build(serviceConsumerResponseDocument);
// Verify IDWS service response for errors
if (response.isFault()) {
log.error("Response error: " + response.getFaultString() + ", error code: " + response.getFaultCode());
return false;
}
// Validate IDWS service response
try {
response.validateSignature();
response.validateSignatureAndTrust(federation);
} catch (ModelBuildException e) {
log.error("Validation error: " + e.getMessage());
return false;
}
return true;
3. Komplet eksempel (incl. STS delen)