Anropa AEM Forms med Web Services invoking-aem-forms-using-web-services

Exempel och exempel i det här dokumentet gäller endast för AEM Forms i JEE-miljö.

De flesta AEM Forms-tjänster i tjänstbehållaren är konfigurerade för att visa en webbtjänst, med fullständigt stöd för generering av WSDL (Web Service Definition Language). Det innebär att du kan skapa proxyobjekt som använder den ursprungliga SOAP i en AEM Forms-tjänst. Därför kan AEM Forms tjänster utbyta och bearbeta följande SOAP:

Med hjälp av webbtjänster kan du utföra samma AEM Forms-tjänståtgärder som du kan med Java API. En fördel med att använda webbtjänster för att anropa AEM Forms-tjänster är att du kan skapa ett klientprogram i en utvecklingsmiljö som stöder SOAP. Ett klientprogram är inte bundet till en specifik utvecklingsmiljö eller programmeringsspråk. Du kan till exempel skapa ett klientprogram med Microsoft Visual Studio .NET och C# som programmeringsspråk.

AEM Forms-tjänster exponeras över SOAP och är WSI Basic Profile 1.1-kompatibla. Web Services Interoperability (WSI) är en öppen standardorganisation som främjar interoperabilitet mellan olika plattformar. Mer information finns i https://www.ws-i.org/.

AEM Forms stöder följande webbtjänststandarder:

Om du vill anropa AEM Forms-tjänster med en webbtjänst skapar du vanligtvis ett proxybibliotek som använder tjänsten WSDL. Avsnittet Anropar AEM Forms med webbtjänster använder JAX-WS för att skapa Java-proxyklasser för att anropa tjänster. (Se Skapa Java-proxyklasser med JAX-WS.)

Du kan hämta en tjänst-WDSL genom att ange följande URL-definition (objekt inom hakparenteser är valfria):

 https://<your_serverhost>:<your_port>/soap/services/<service_name>?wsdl[&version=<version>][&async=true|false][lc_version=<lc_version>]

där:

I följande tabell visas WSDL-definitioner för tjänsten (förutsatt att AEM Forms har distribuerats på den lokala värden och att posten är 8080).

WSDL-definitioner för AEM Forms Process

Ange programnamnet och processnamnet i WSDL-definitionen för att få åtkomst till en WSDL som tillhör en process som skapats i Workbench. Anta att programnamnet är MyApplication och processens namn är EncryptDocument. Ange i så fall följande WSDL-definition:

 http://localhost:8080/soap/services/MyApplication/EncryptDocument?wsdl

 http://localhost:8080/soap/services/MyApplication/[<folderA>/.../<folderZ>/]EncryptDocument?wsdl

Åtkomst till nya funktioner med webbtjänster

Du kommer åt de nya funktionerna i AEM Forms-tjänsten via webbtjänster. I AEM Forms introduceras till exempel möjligheten att koda bilagor med hjälp av MTOM. (Se Anropa AEM Forms med MTOM.)

Om du vill få åtkomst till nya funktioner som introducerats i AEM Forms anger du attributet lc_version i WSDL-definitionen. Om du till exempel vill få åtkomst till nya tjänstfunktioner (inklusive stöd för MTOM) anger du följande WSDL-definition:

 http://localhost:8080/soap/services/MyApplication/EncryptDocument?wsdl&lc_version=9.0.1

Webbtjänstens BLOB-datatyp

WSDL:er för AEM Forms-tjänster definierar många datatyper. En av de viktigaste datatyperna som visas i en webbtjänst är en BLOB-typ. Den här datatypen mappar till klassen com.adobe.idp.Document när du arbetar med AEM Forms Java API:er. (Se Skicka data till AEM Forms-tjänster med Java API.)

Ett BLOB-objekt skickar och hämtar binära data (till exempel PDF-filer, XML-data osv.) till och från AEM Forms-tjänster. Typen BLOB definieras i en tjänst-WSDL på följande sätt:

 <complexType name="BLOB">
     <sequence>
         <element maxOccurs="1" minOccurs="0" name="contentType"
             type="xsd:string"/>
         <element maxOccurs="1" minOccurs="0" name="binaryData"
             type="xsd:base64Binary"/>
         <element maxOccurs="1" minOccurs="0" name="attachmentID"
             type="xsd:string"/>
         <element maxOccurs="1" minOccurs="0" name="remoteURL"
             type="xsd:string"/>
         <element maxOccurs="1" minOccurs="0" name="MTOM"
             type="xsd:base64Binary"
             xmime:expectedContentTypes="*/*"
             xmlns:xmime="https://www.w3.org/2005/05/xmlmime"/>
         <element maxOccurs="1" minOccurs="0" name="swaRef"
             type="tns1:swaRef"/>
         <element maxOccurs="1" minOccurs="0" name="attributes"
             type="impl:MyMapOf_xsd_string_To_xsd_anyType"/>
     </sequence>
 </complexType>

Fälten MTOM och swaRef stöds bara i AEM Forms. Du kan bara använda dessa nya fält om du anger en URL som innehåller egenskapen lc_version.

Tillhandahåller BLOB-objekt i tjänstförfrågningar

Om en AEM Forms-tjänståtgärd kräver en BLOB-typ som indatavärde skapar du en instans av typen BLOB i programlogiken. (Många av webbtjänstens snabbkommandon börjar i Programmering med AEM formulär visar hur du arbetar med en BLOB-datatyp.)

Tilldela värden till fält som tillhör instansen BLOB enligt följande:

Åtkomst till data i BLOB-objekt som returnerats från tjänster

Överföringsprotokollet för returnerade BLOB-objekt är beroende av flera faktorer, som beaktas i följande ordning och som avbryts när huvudvillkoret är uppfyllt:

Så som beskrivs i det första villkoret kan du säkerställa överföringstypen för returnerade dokument genom att utöka SOAP URL med ett suffix enligt följande:

     https://<your_serverhost>:<your_port>/soap/services/<service
     name>?blob=base64|dime|mime|http|mtom|swaref

Här är korrelationen mellan överföringstyper och det fält från vilket du får data:

MTOM-överföring av base64-kodade bytearrayer

Utöver objektet BLOB stöder MTOM-protokollet alla byte-array-parametrar eller byte-array-fält av komplex typ. Det innebär att klientens SOAP som stöder MTOM kan skicka vilket xsd:base64Binary-element som helst som en MTOM-bilaga (i stället för en base64-kodad text). AEM Forms SOAP-slutpunkter kan läsa den här typen av byte-array-kodning. AEM Forms-tjänsten returnerar emellertid alltid en bytearraytyp som base64-kodad text. Parametrarna för byte-array i utdata stöder inte MTOM.

AEM Forms-tjänster som returnerar en stor mängd binära data använder typen Dokument/BLOB i stället för bytearraytypen. Dokumenttypen är mycket effektivare när du vill skicka stora mängder data.

Datatyper för webbtjänster web-service-data-types

I följande tabell visas Java-datatyper och motsvarande webbtjänstdatatyp.

Skapa Java-proxyklasser med JAX-WS creating-java-proxy-classes-using-jax-ws

Du kan använda JAX-WS för att konvertera en Forms-tjänst-WSDL till Java-proxyklasser. Med de här klasserna kan du anropa åtgärder för AEM Forms-tjänster. Med Apache Ant kan du skapa ett byggskript som genererar Java-proxyklasser genom att referera till en AEM Forms-tjänst-WSDL. Du kan generera JAX-WS-proxyfiler genom att utföra följande steg:

Se även

Skapa Java-proxyklasser med Apache-axeln

Anropa AEM Forms med Base64-kodning

Anropa AEM Forms med BLOB-data via HTTP

Anropa AEM Forms med SwaRef

Skapa Java-proxyklasser med Apache-axeln creating-java-proxy-classes-using-apache-axis

Med verktyget Apache Axis WSDL2Java kan du konvertera en Forms-tjänst till Java-proxyklasser. Med dessa klasser kan du anropa Forms serviceåtgärder. Med Apache Ant kan du generera axelbiblioteksfiler från en tjänst-WSDL. Du kan hämta Apache-axeln på URL:en https://ws.apache.org/axis/.

Du kan generera Axis Java-biblioteksfiler genom att utföra följande steg:

Se även

Skapa Java-proxyklasser med JAX-WS

Anropa AEM Forms med Base64-kodning

Anropa AEM Forms med BLOB-data via HTTP

Anropa AEM Forms med Base64-kodning invoking-aem-forms-using-base64-encoding

Du kan anropa en AEM Forms-tjänst med Base64-kodning. Base64-kodning kodar bilagor som skickas med en webbtjänstanrop. Det vill säga, BLOB-data är Base64-kodade, inte hela SOAP.

Anrop av AEM Forms med Base64-kodning diskuterar anrop av följande kortlivade AEM Forms-process med namnet MyApplication/EncryptDocument med Base64-kodning.

När processen anropas utför den följande åtgärder:

Skapa en .NET-klientsammansättning som använder Base64-kodning creating-a-net-client-assembly-that-uses-base64-encoding

Du kan skapa en .NET-klientsammansättning för att anropa en Forms-tjänst från ett Microsoft Visual Studio .NET-projekt. Så här skapar du en .NET-klientsammansättning som använder base64-kodning:

Skapa en proxyklass

Du kan skapa en proxyklass som används för att skapa .NET-klientsammansättningen med ett verktyg som medföljer Microsoft Visual Studio. Namnet på verktyget är wsdl.exe och finns i installationsmappen för Microsoft Visual Studio. Om du vill skapa en proxyklass öppnar du kommandotolken och navigerar till mappen som innehåller filen wsdl.exe. Mer information om verktyget wsdl.exe finns i MSDN-hjälpen.

Ange följande kommando i kommandotolken:

 wsdl https://hiro-xp:8080/soap/services/MyApplication/EncryptDocument?WSDL&lc_version=9.0.1

Som standard skapas en CS-fil i samma mapp som baseras på namnet på WSDL. I det här fallet skapas en CS-fil med namnet EncryptDocumentService.cs. Du använder den här CS-filen för att skapa ett proxyobjekt som gör att du kan anropa tjänsten som angavs i anrops-URL:en.

Ändra URL:en i proxyklassen så att den innehåller ?blob=base64, så att objektet BLOB returnerar binära data. Leta reda på följande kodrad i klassen proxy:

 "https://hiro-xp:8080/soap/services/MyApplication/EncryptDocument";

och ändra det till:

 "https://hiro-xp:8080/soap/services/MyApplication/EncryptDocument?blob=base64";

Avsnittet Anropar AEM Forms med Base64-kodning använder MyApplication/EncryptDocument som exempel. Om du skapar en .NET-klientsammansättning för en annan Forms-tjänst måste du ersätta MyApplication/EncryptDocument med namnet på tjänsten.

Utveckla .NET-klientsammansättningen

Skapa ett Visual Studio Class Library-projekt som skapar en .NET-klientsammansättning. CS-filen som du skapade med wsdl.exe kan importeras till det här projektet. Det här projektet skapar en DLL-fil (.NET-klientsammansättningen) som du kan använda i andra Visual Studio .NET-projekt för att anropa en tjänst.

Refererar till .NET-klientsammansättningen

Placera den nyligen skapade .NET-klientsammansättningen på den dator där du utvecklar klientprogrammet. När du har placerat .NET-klientsammansättningen i en katalog kan du referera till den från ett projekt. Referera även till biblioteket System.Web.Services från ditt projekt. Om du inte refererar till det här biblioteket kan du inte använda .NET-klientsammansättningen för att anropa en tjänst.

Anropar en tjänst med en .NET-klientsammansättning som använder Base64-kodning

Du kan anropa tjänsten MyApplication/EncryptDocument (som skapades i Workbench) med en .NET-klientsammansättning som använder Base64-kodning. Så här anropar du tjänsten MyApplication/EncryptDocument:

Anropa en tjänst med Java-proxyklasser och Base64-kodning invoking-a-service-using-java-proxy-classes-and-base64-encoding

Du kan anropa en AEM Forms-tjänst med hjälp av Java-proxyklasser och Base64. Så här anropar du tjänsten MyApplication/EncryptDocument med Java-proxyklasser:

Se även

Snabbstart: Anropa en tjänst med Java-proxyfiler och Base64-kodning

Skapa en .NET-klientsammansättning som använder Base64-kodning

Anropa AEM Forms med MTOM invoking-aem-forms-using-mtom

Du kan anropa AEM Forms-tjänster med hjälp av webbtjänststandarden MTOM. Den här standarden definierar hur binära data, till exempel ett PDF-dokument, överförs via Internet eller intranätet. En funktion i MTOM är användningen av elementet XOP:Include. Det här elementet definieras i XOP-specifikationen (XML Binary Optimized Packaging) för att referera till binära bilagor i ett SOAP.

Diskussionen här handlar om att använda MTOM för att anropa följande kortlivade AEM Forms-process med namnet MyApplication/EncryptDocument.

När processen anropas utför den följande åtgärder:

Här handlar det om att använda MTOM i ett Microsoft .NET-projekt för att anropa AEM Forms tjänster. Det .NET Framework som används är 3.5 och utvecklingsmiljön är Visual Studio 2008. Om du har WSE (Web Service Enhancements) installerat på utvecklingsdatorn tar du bort det. .NET 3.5-ramverket stöder ett SOAP ramverk som heter Windows Communication Foundation (WCF). När AEM Forms anropas med hjälp av MTOM stöds bara WCF (inte WSE).

Skapa ett .NET-projekt som anropar en tjänst med hjälp av MTOM creating-a-net-project-that-invokes-a-service-using-mtom

Du kan skapa ett Microsoft .NET-projekt som kan anropa en AEM Forms-tjänst med hjälp av webbtjänster. Skapa först ett Microsoft .NET-projekt med Visual Studio 2008. Om du vill anropa en AEM Forms-tjänst skapar du en servicereferens till den AEM Forms-tjänst som du vill anropa i ditt projekt. När du skapar en servicereferens anger du en URL till AEM Forms-tjänsten:

 http://localhost:8080/soap/services/MyApplication/EncryptDocument?WSDL&lc_version=9.0.1

Ersätt localhost med IP-adressen för J2EE-programservern som är värd för AEM Forms. Ersätt MyApplication/EncryptDocument med namnet på den AEM Forms-tjänst som ska anropas. Om du till exempel vill anropa en Rights Management-åtgärd anger du:

http://localhost:8080/soap/services/RightsManagementService?WSDL&lc_version=9.0.1

Alternativet lc_version ser till att AEM Forms-funktioner, som MTOM, är tillgängliga. Om du inte anger alternativet lc_version kan du inte anropa AEM Forms med MTOM.

När du har skapat en servicereferens är datatyper som är kopplade till AEM Forms-tjänsten tillgängliga för användning i ditt .NET-projekt. Så här skapar du ett .NET-projekt som anropar en AEM Forms-tjänst:

Anropa en tjänst med MTOM i ett .NET-projekt invoking-a-service-using-mtom-in-a-net-project

Överväg MyApplication/EncryptDocument-processen som accepterar ett oskyddat PDF-dokument och returnerar ett lösenordskrypterat PDF-dokument. Så här anropar du processen MyApplication/EncryptDocument (som skapades i Workbench) med hjälp av MTOM:

Se även

Snabbstart: Anropa en tjänst med MTOM i ett .NET-projekt

Åtkomst av flera tjänster via webbtjänster

Skapa ett ASP.NET webbprogram som anropar en människocentrerad, lång process

Anropa AEM Forms med SwaRef invoking-aem-forms-using-swaref

Du kan anropa AEM Forms-tjänster med SwaRef. Innehållet i XML-elementet wsi:swaRef skickas som en bifogad fil i en SOAP som lagrar referensen till den bifogade filen. Skapa Java-proxyklasser med Java API för XML-webbtjänster (JAX-WS) när du anropar en Forms-tjänst med hjälp av SwaRef. (Se Java API for XML Web Services.)

Diskussionen här handlar om att anropa följande kortlivade Forms-process med namnet MyApplication/EncryptDocument med hjälp av SwaRef.

När processen anropas utför den följande åtgärder:

Nedan beskrivs hur du anropar Forms-tjänster med hjälp av SwaRef i ett Java-klientprogram. Java-programmet använder proxyklasser som skapats med JAX-WS.

Anropa en tjänst med JAX-WS-biblioteksfiler som använder SwaRef invoke-a-service-using-jax-ws-library-files-that-use-swaref

Så här anropar du processen MyApplication/EncryptDocument med Java-proxyfiler som skapats med JAX-WS och SwaRef:

Se även

Snabbstart: Anropa en tjänst med SwaRef i ett Java-projekt

Anropa AEM Forms med BLOB-data via HTTP invoking-aem-forms-using-blob-data-over-http

Du kan anropa AEM Forms-tjänster med webbtjänster och skicka BLOB-data via HTTP. Att skicka BLOB-data via HTTP är en alternativ teknik i stället för att använda base64-kodning, DIME eller MIME. Du kan till exempel skicka data via HTTP i ett Microsoft .NET-projekt som använder Web Service Enhancement 3.0, som inte stöder DIME eller MIME. När du använder BLOB-data över HTTP överförs indata innan AEM Forms-tjänsten anropas.

Anrop av AEM Forms med BLOB Data via HTTP diskuterar anrop av följande kortlivade AEM Forms-process med namnet MyApplication/EncryptDocument genom att skicka BLOB-data via HTTP.

När processen anropas utför den följande åtgärder:

Skapa en .NET-klientsammansättning som använder data över HTTP creating-a-net-client-assembly-that-uses-data-over-http

Om du vill skapa en klientsammansättning som använder data över HTTP följer du den process som anges i Anropa AEM Forms med Base64-kodning. Ändra emellertid URL:en i proxyklassen så att den innehåller ?blob=http i stället för ?blob=base64. Den här åtgärden ser till att data skickas via HTTP. Leta reda på följande kodrad i klassen proxy:

 "http://localhost:8080/soap/services/MyApplication/EncryptDocument";

och ändra det till:

 "http://localhost:8080/soap/services/MyApplication/EncryptDocument?blob=http";

Refererar till .NET clienMyApplication/EncryptDocument-sammansättningen

Placera den nya .NET-klientsammansättningen på den dator där du utvecklar klientprogrammet. När du har placerat .NET-klientsammansättningen i en katalog kan du referera till den från ett projekt. Referera biblioteket System.Web.Services från ditt projekt. Om du inte refererar till det här biblioteket kan du inte använda .NET-klientsammansättningen för att anropa en tjänst.

Anropar en tjänst med en .NET-klientsammansättning som använder BLOB-data via HTTP

Du kan anropa tjänsten MyApplication/EncryptDocument (som skapades i Workbench) med en .NET-klientsammansättning som använder data via HTTP. Så här anropar du tjänsten MyApplication/EncryptDocument:

Anropa en tjänst med Java-proxyklasser och BLOB-data via HTTP invoking-a-service-using-java-proxy-classes-and-blob-data-over-http

Du kan anropa en AEM Forms-tjänst med hjälp av Java-proxyklasser och BLOB-data via HTTP. Så här anropar du tjänsten MyApplication/EncryptDocument med Java-proxyklasser:

Anropa AEM Forms med DIME invoking-aem-forms-using-dime

Du kan anropa AEM Forms-tjänster med SOAP med bifogade filer. AEM Forms stöder både MIME- och DIME-webbtjänststandarderna. Med DIME kan du skicka binära bilagor, t.ex. PDF-dokument, tillsammans med anropsbegäranden i stället för att koda bilagan. Avsnittet Anropa AEM Forms med DIME diskuterar att anropa följande kortlivade AEM Forms-process som heter MyApplication/EncryptDocument med DIME.

När processen anropas utför den följande åtgärder:

Processen bygger inte på någon befintlig AEM Forms-process. Om du vill följa med i kodexemplen skapar du en process med namnet MyApplication/EncryptDocument med Workbench. (Se Använda Workbench.)

Skapa ett .NET-projekt som använder DIME creating-a-net-project-that-uses-dime

Så här skapar du ett .NET-projekt som kan anropa en Forms-tjänst med DIME:

Installerar Web Services-förbättringar 2.0

Installera Web Services Enhancements 2.0 på utvecklingsdatorn och integrera den med Microsoft Visual Studio .NET. Du kan hämta webbtjänsttillägg 2.0 från Microsoft Download Center.

På den här webbsidan söker du efter Web Services Enhancements 2.0 och laddar ned det till utvecklingsdatorn. Den här nedladdningen placerar en fil med namnet Microsoft WSE 2.0 SPI.msi på datorn. Kör installationsprogrammet och följ anvisningarna online.

Skapa en webbreferens till en AEM Forms-tjänst

När du har installerat Web Services Enhancements 2.0 på utvecklingsdatorn och skapat ett Microsoft .NET-projekt skapar du en webbreferens till Forms-tjänsten. Om du till exempel vill skapa en webbreferens till processen MyApplication/EncryptDocument och anta att Forms är installerat på den lokala datorn anger du följande URL:

     http://localhost:8080/soap/services/MyApplication/EncryptDocument?WSDL

När du har skapat en webbreferens är följande två proxydatatyper tillgängliga som du kan använda i ditt .NET-projekt: EncryptDocumentService och EncryptDocumentServiceWse. Använd typen EncryptDocumentServiceWse om du vill anropa MyApplication/EncryptDocument-processen med DIME.

Referera till WSE-biblioteket

Skapa en webbreferens till en Forms-tjänst

Anropar en tjänst med DIME i ett .NET-projekt

Du kan anropa en Forms-tjänst med DIME. Överväg MyApplication/EncryptDocument-processen som accepterar ett oskyddat PDF-dokument och returnerar ett lösenordskrypterat PDF-dokument. Så här anropar du MyApplication/EncryptDocument-processen med DIME:

Skapa Java-proxyklasser för Apache-axel som använder DIME creating-apache-axis-java-proxy-classes-that-use-dime

Du kan använda verktyget WSDL2Java på Apache-axeln för att konvertera en tjänst-WSDL till Java-proxyklasser så att du kan anropa tjänståtgärder. Med Apache Ant kan du generera axelbiblioteksfiler från en AEM Forms-tjänst-WSDL som gör att du kan anropa tjänsten. (Se Skapa Java-proxyklasser med Apache Axis.)

Verktyget Apache Axel WSDL2Java genererar JAVA-filer som innehåller metoder som används för att skicka SOAP till en tjänst. SOAP som tas emot av en tjänst avkodas av de axelgenererade biblioteken och återställs till metoder och argument.

Så här anropar du tjänsten MyApplication/EncryptDocument (som skapades i Workbench) med axelgenererade biblioteksfiler och DIME:

Se även

Snabbstart: Anropa en tjänst med DIME i ett Java-projekt

Använda SAML-baserad autentisering using-saml-based-authentication

AEM Forms har stöd för olika autentiseringslägen för webbtjänster vid anrop av tjänster. Ett autentiseringsläge anger både ett användarnamn och ett lösenordsvärde med hjälp av ett grundläggande auktoriseringshuvud i webbtjänstanropet. AEM Forms stöder också SAML-baserad autentisering. När ett klientprogram anropar en AEM Forms-tjänst med hjälp av en webbtjänst kan klientprogrammet tillhandahålla autentiseringsinformation på något av följande sätt:

AEM Forms stöder inte standardcertifikatbaserad autentisering, men stöder certifikatbaserad autentisering i en annan form.

Identiteten hos AEM formuläranvändare kan representeras via en SAML-försäkran som signerats med en hemlig nyckel. Följande XML-kod visar ett exempel på en SAML-försäkran.

 <Assertion xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
     xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
     xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
     AssertionID="fd4bd0c87302780e0d9bbfa8726d5bc0" IssueInstant="2008-04-17T13:47:00.720Z" Issuer="LiveCycle"
     MajorVersion="1" MinorVersion="1">
     <Conditions NotBefore="2008-04-17T13:47:00.720Z" NotOnOrAfter="2008-04-17T15:47:00.720Z">
     </Conditions>
     <AuthenticationStatement
         AuthenticationInstant="2008-04-17T13:47:00.720Z"
         AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:unspecified">
         <Subject>
             <NameIdentifier NameQualifier="DefaultDom">administrator</NameIdentifier>
             <SubjectConfirmation>
                 <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</ConfirmationMethod>
             </SubjectConfirmation>
         </Subject>
     </AuthenticationStatement>
     <ds:Signature >
         <ds:SignedInfo>
             <ds:CanonicalizationMethod Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
             <ds:SignatureMethod    Algorithm="https://www.w3.org/2000/09/xmldsig#hmac-sha1"></ds:SignatureMethod>
             <ds:Reference URI="#fd4bd0c87302780e0d9bbfa8726d5bc0">
                 <ds:Transforms>
                     <ds:Transform Algorithm="https://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:Transform>
                     <ds:Transform Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#">
                         <ec:InclusiveNamespaces
                             PrefixList="code ds kind rw saml samlp typens #default">
                         </ec:InclusiveNamespaces>
                     </ds:Transform>
                 </ds:Transforms>
                 <ds:DigestMethod Algorithm="https://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
                 <ds:DigestValue>hVrtqjWr+VzaVUIpQx0YI9lIjaY=</ds:DigestValue>
             </ds:Reference>
         </ds:SignedInfo>
         <ds:SignatureValue>UMbBb+cUcPtcWDCIhXes4n4FxfU=</ds:SignatureValue>
     </ds:Signature>
 </Assertion>

Det här exempelbekräftelsen utfärdas för en administratörsanvändare. Påståendet innehåller följande märkbara objekt:

Ett klientprogram kan hämta försäkran från ett AEM Forms AuthenticationManager-API som returnerar ett AuthResult-objekt. Du kan hämta en AuthResult-instans genom att utföra någon av följande två metoder:

En AEM kan autentiseras med en SAML-token som erhålls. Denna SAML-försäkran (xml-fragment) kan skickas som en del av WS-Security-huvudet med webbtjänstanropet för användarautentisering. Vanligtvis har ett klientprogram autentiserat en användare men inte lagrat inloggningsuppgifterna. (Eller så har användaren loggat in på klienten via en annan mekanism än att använda ett användarnamn och lösenord.) I den här situationen måste klientprogrammet anropa AEM Forms och personifiera en specifik användare som kan anropa AEM Forms.

Anropa metoden AuthenticationManager.getAuthResultOnBehalfOfUser med en webbtjänst om du vill personifiera en viss användare. Den här metoden returnerar en AuthResult-instans som innehåller SAML-försäkran för den användaren.

Använd sedan SAML-försäkran för att anropa alla tjänster som kräver autentisering. Den här åtgärden innebär att försäkran skickas som en del av SOAP. När ett webbtjänstanrop görs med denna försäkran identifierar AEM Forms användaren som den som representeras av försäkran. Användaren som anges i försäkran är alltså den användare som anropar tjänsten.

Använda Apache-axelklasser och SAML-baserad autentisering using-apache-axis-classes-and-saml-based-authentication

Du kan anropa en AEM Forms-tjänst av Java-proxyklasser som har skapats med axelbiblioteket. (Se Skapa Java-proxyklasser med Apache Axis.)

När du använder AXIS som använder SAML-baserad autentisering registrerar du hanteraren för begäran och svar med Axel. Hanteraren anropas av Apache Axis innan en anropsbegäran skickas till AEM Forms. Om du vill registrera en hanterare skapar du en Java-klass som utökar org.apache.axis.handlers.BasicHandler.

Skapa en AssertionHandler med Axis

Följande Java-klass, med namnet AssertionHandler.java, visar ett exempel på en Java-klass som utökar org.apache.axis.handlers.BasicHandler.

 public class AssertionHandler extends BasicHandler {
        public void invoke(MessageContext ctx) throws AxisFault {
            String assertion = (String) ctx.getProperty(LC_ASSERTION);

            //no assertion hence nothing to insert
            if(assertion == null) return;

            try {
                MessageElement samlElement = new MessageElement(convertToXML(assertion));
                SOAPHeader header = (SOAPHeader) ctx.getRequestMessage().getSOAPHeader();
                //Create the wsse:Security element which would contain the SAML element
                SOAPElement wsseHeader = header.addChildElement("Security", "wsse", WSSE_NS);
                wsseHeader.appendChild(samlElement);
                //remove the actor attribute as in LC we do not specify any actor. This would not remove the actor attribute though
                //it would only remove it from the soapenv namespace
                wsseHeader.getAttributes().removeNamedItem("actor");
            } catch (SOAPException e) {
                throw new AxisFault("Error occured while adding the assertion to the SOAP Header",e);
            }
        }
 }

Registrera hanteraren

Om du vill registrera en hanterare med Axel skapar du en client-config.wsdd-fil. Axeln söker som standard efter en fil med det här namnet. Följande XML-kod är ett exempel på en client-config.wsdd-fil. Mer information finns i Axeldokumentationen.

 <deployment xmlns="https://xml.apache.org/axis/wsdd/" xmlns:java="https://xml.apache.org/axis/wsdd/providers/java">
     <transport name="http" pivot="java:org.apache.axis.transport.http.HTTPSender"/>
      <globalConfiguration >
       <requestFlow >
        <handler type="java:com.adobe.idp.um.example.AssertionHandler" />
       </requestFlow >
      </globalConfiguration >
 </deployment>

Anropa en AEM Forms-tjänst

I följande kodexempel anropas en AEM Forms-tjänst med SAML-baserad autentisering.

 public class ImpersonationExample {
        . . .
        public void  authenticateOnBehalf(String superUsername,String password,
                String canonicalName,String domainName) throws UMException, RemoteException{
            ((org.apache.axis.client.Stub) authenticationManager).setUsername(superUsername);
            ((org.apache.axis.client.Stub) authenticationManager).setPassword(password);

            //Step 1 - Invoke the Auth manager api to get an assertion for the user to be impersonated
            AuthResult ar = authenticationManager.getAuthResultOnBehalfOfUser(canonicalName, domainName, null);
            String assertion = ar.getAssertion();
            //Step 2 - Setting the assertion here to be picked later by the AssertionHandler. Note that stubs are not threadSafe
            //hence should not be reused. For this simple example we have made them instance variable but care should be taken
            //regarding the thread safety
            ((javax.xml.rpc.Stub) authorizationManager)._setProperty(AssertionHandler.LC_ASSERTION, assertion);
        }

        public Role findRole(String roleId) throws UMException, RemoteException{
            //This api would be invoked under bob's user rights
            return authorizationManager.findRole(roleId);
        }

        public static void main(String[] args) throws Exception {
            ImpersonationExample ie = new ImpersonationExample("http://localhost:5555");
            //Get the SAML assertion for the user to impersonate and store it in stub
            ie.authenticateOnBehalf(
                    "administrator", //The Super user which has the required impersonation permission
                    "password", // Password of the super user as referred above
                    "bob", //Cannonical name of the user to impersonate
                    "testdomain" //Domain of the user to impersonate
                    );

            Role r = ie.findRole("BASIC_ROLE_ADMINISTRATOR");
            System.out.println("Role "+r.getName());
        }
 }

Använda en .NET-klientsammansättning och SAML-baserad autentisering using-a-net-client-assembly-and-saml-based-authentication

Du kan anropa en Forms-tjänst genom att använda en .NET-klientsammansättning och SAML-baserad autentisering. För att göra det måste du använda Web Service Enhancements 3.0 (WSE). Mer information om hur du skapar en .NET-klientsammansättning som använder WSE finns i Skapa ett .NET-projekt som använder DIME.

WSE-arkitekturen använder datatyperna Policies, Assertions och SecurityToken. För ett webbtjänstanrop anger du kort en princip. En princip kan ha flera försäkringar. Varje försäkran kan innehålla filter. Ett filter anropas i vissa steg i ett webbtjänstanrop och kan då ändra SOAP. Mer information finns i dokumentationen till Web Service Enhancements 3.0.

Skapa försäkran och filter

I följande exempel på C#-kod skapas filter- och kontrollklasser. I det här kodexemplet skapas ett SamlAssertionOutputFilter. Filtret anropas av WSE-ramverket innan SOAP skickas till AEM Forms.

 class LCSamlPolicyAssertion : Microsoft.Web.ServicES4.Design.PolicyAssertion
 {
        public override Microsoft.Web.ServicES4.SoapFilter CreateClientOutputFilter(FilterCreationContext context)
        {
           return new SamlAssertionOutputFilter();
        }
        . . .
 }


 class SamlAssertionOutputFilter : SendSecurityFilter
 {
        public override void SecureMessage(SoapEnvelope envelope, Security security)
        {
           // Get the SamlToken from the SessionState
           SamlToken samlToken = envelope.Context.Credentials.UltimateReceiver.GetClientToken<SamlToken>();
           security.Tokens.Add(samlToken);
        }
 }

Skapa SAML-token

Skapa en klass som representerar SAML-försäkran. Huvuduppgiften som den här klassen utför är att konvertera datavärden från sträng till xml och bevara tomt utrymme. Denna XML för försäkran importeras senare till SOAP.

 class SamlToken : SecurityToken
 {
        public const string SAMLAssertion = "https://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1";
        private XmlElement _assertionElement;

        public SamlToken(string assertion)
             : base(SAMLAssertion)
        {
           XmlDocument xmlDoc = new XmlDocument();
           //The white space has to be preserved else the digital signature would get broken
           xmlDoc.PreserveWhitespace = true;
           xmlDoc.LoadXml(assertion);
           _assertionElement = xmlDoc.DocumentElement;
         }

         public override XmlElement GetXml(XmlDocument document)
         {
            return (XmlElement)document.ImportNode(_assertionElement, true);
         }
        . . .
 }

Anropa en AEM Forms-tjänst

Följande C#-kodexempel anropar en Forms-tjänst med SAML-baserad autentisering.

 public class ImpersonationExample
 {
        . . .
        public void AuthenticateOnBehalf(string superUsername, string password, string canonicalName, string domainName)
        {
            //Create a policy for UsernamePassword Token
            Policy usernamePasswordPolicy = new Policy();
            usernamePasswordPolicy.Assertions.Add(new UsernameOverTransportAssertion());

            UsernameToken token = new UsernameToken(superUsername, password, PasswordOption.SendPlainText);
            authenticationManager.SetClientCredential(token);
            authenticationManager.SetPolicy(usernamePasswordPolicy);

            //Get the SAML assertion for impersonated user
            AuthClient.AuthenticationManagerService.AuthResult ar
                = authenticationManager.getAuthResultOnBehalfOfUser(canonicalName, domainName, null);
            System.Console.WriteLine("Received assertion " + ar.assertion);

            //Create a policy for inserting SAML assertion
            Policy samlPolicy = new Policy();
            samlPolicy.Assertions.Add(new LCSamlPolicyAssertion());
            authorizationManager.SetPolicy(samlPolicy);
            //Set the SAML assertion obtained previously as the token
            authorizationManager.SetClientCredential(new SamlToken(ar.assertion));
        }

        public Role findRole(string roleId)
        {
            return authorizationManager.findRole(roleId);
        }

        static void Main(string[] args)
        {
            ImpersonationExample ie = new ImpersonationExample("http://localhost:5555");
            ie.AuthenticateOnBehalf(
                 "administrator", //The Super user which has the required impersonation permission
                 "password", // Password of the super user as referred above
                 "bob", //Cannonical name of the user to impersonate
                 "testdomain" //Domain of the user to impersonate
                 );

         Role r = ie.findRole("BASIC_ROLE_ADMINISTRATOR");
            System.Console.WriteLine("Role "+r.name);
     }
 }

Relaterade överväganden när du använder webbtjänster related-considerations-when-using-web-services

Ibland uppstår problem när vissa AEM Forms-tjänster anropas med hjälp av webbtjänster. Syftet med denna diskussion är att identifiera dessa problem och tillhandahålla en lösning, om en sådan finns tillgänglig.

Anropa tjänståtgärder asynkront invoking-service-operations-asynchronously

Om du försöker anropa en AEM Forms-tjänståtgärd asynkront, till exempel åtgärden Generate PDF htmlToPDF , inträffar en SoapFaultException . Du löser det här problemet genom att skapa en anpassad XML-fil som mappar elementet ExportPDF_Result och andra element till olika klasser. Följande XML representerar en anpassad bindningsfil.

 <bindings
        xmlns:xsd="https://www.w3.org/2001/XMLSchema"
        xmlns:jxb="https://java.sun.com/xml/ns/jaxb" jxb:version="1.0"
        xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/"
      wsdlLocation="http://localhost:8080/soap/services/GeneratePDFService?wsdl&async=true&lc_version=9.0.0"
        xmlns="https://java.sun.com/xml/ns/jaxws">
        <enableAsyncMapping>false</enableAsyncMapping>
        <package name="external_customize.client"/>
        <enableWrapperStyle>true</enableWrapperStyle>
        <bindings node="/wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='https://adobe.com/idp/services']/xsd:element[@name='ExportPDF_Result']">
            <jxb:class name="ExportPDFAsyncResult">
            </jxb:class>
        </bindings>
        <bindings node="/wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='https://adobe.com/idp/services']/xsd:element[@name='CreatePDF_Result']">
            <jxb:class name="CreatePDFAsyncResult">
            </jxb:class>
        </bindings>
        <bindings node="/wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='https://adobe.com/idp/services']/xsd:element[@name='HtmlToPDF_Result']">
            <jxb:class name="HtmlToPDFAsyncResult">
            </jxb:class>
        </bindings>
        <bindings node="/wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='https://adobe.com/idp/services']/xsd:element[@name='OptimizePDF_Result']">
            <jxb:class name="OptimizePDFAsyncResult">
            </jxb:class>
        </bindings>
        <!--bindings node="//wsdl:portType[@name='GeneratePDFService']/wsdl:operation[@name='HtmlToPDF_Result']">
            <jxb:class name="HtmlToPDFAsyncResult"/>
        </bindings-->
 </bindings>

Använd XML-filen när du skapar Java-proxyfiler med JAX-WS. (Se Skapa Java-proxyklasser med JAX-WS.)

Referera till den här XML-filen när du kör JAX-WS-verktyget (wsimport.exe) med kommandoradsalternativet - b. Uppdatera elementet wsdlLocation i XML-bindningsfilen för att ange URL:en för AEM Forms.

Om du vill vara säker på att asynkrona anrop fungerar ändrar du URL-värdet för slutpunkten och anger async=true. För Java-proxyfiler som skapas med JAX-WS anger du till exempel följande för BindingProvider.ENDPOINT_ADDRESS_PROPERTY.

https://server:port/soap/services/ServiceName?wsdl&async=true&lc_version=9.0.0

I följande lista anges andra tjänster som behöver en anpassad bindningsfil när den anropas asynkront:

Skillnader i J2EE-servrar differences-in-j2ee-application-servers

Ibland kan ett proxybibliotek som skapats med en viss J2EE-programserver inte anropa AEM Forms som finns på en annan J2EE-programserver. Överväg ett proxybibliotek som genereras med AEM Forms och som distribueras på WebSphere. Proxybiblioteket kan inte anropa AEM Forms-tjänster som är distribuerade på JBoss Application Server.

Vissa komplexa AEM Forms-datatyper, som PrincipalReference, definieras annorlunda när AEM Forms distribueras på WebSphere jämfört med JBoss Application Server. Skillnader i de JDK:er som används av de olika J2EE-programtjänsterna är orsaken till varför det finns skillnader i WSDL-definitioner. Använd därför proxybibliotek som genereras från samma J2EE-programserver.

Åtkomst av flera tjänster via webbtjänster accessing-multiple-services-using-web-services

På grund av namnområdeskonflikter kan dataobjekt inte delas mellan flera tjänst-WSDL:er. Olika tjänster kan dela datatyper och därför delar tjänsterna definitionen av dessa typer i WSDL:erna. Du kan till exempel inte lägga till två .NET-klientsammansättningar som innehåller datatypen BLOB i samma .NET-klientprojekt. Om du försöker göra det inträffar ett kompileringsfel.

I följande lista anges datatyper som inte kan delas mellan flera tjänst-WSDL

För att undvika det här problemet rekommenderar vi att du kvalificerar datatyperna fullständigt. Ta till exempel ett .NET-program som refererar både till Forms-tjänsten och signaturtjänsten med hjälp av en tjänstreferens. Båda tjänstreferenserna innehåller en BLOB-klass. Om du vill använda en BLOB-instans kvalificerar du BLOB-objektet fullständigt när du deklarerar det. Den här metoden visas i följande kodexempel. Mer information om det här kodexemplet finns i Digital Signing Interactive Forms.

Följande exempel på C#-kod signerar ett interaktivt formulär som återges av Forms-tjänsten. Klientprogrammet har två tjänstreferenser. BLOB-instansen som är associerad med Forms-tjänsten tillhör namnutrymmet SignInteractiveForm.ServiceReference2. På samma sätt tillhör instansen BLOB som är associerad med signaturtjänsten namnutrymmet SignInteractiveForm.ServiceReference1. Det signerade interaktiva formuläret sparas som en PDF-fil med namnet LoanXFASigned.pdf.

 ???/**
     * Ensure that you create a .NET project that uses
     * MS Visual Studio 2008 and version 3.5 of the .NET
     * framework. This is required to invoke a
     * AEM Forms service using MTOM.
     *
     * For information, see "Invoking AEM Forms using MTOM" in Programming with AEM forms
     */
 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
 using System.ServiceModel;
 using System.IO;

 //A reference to the Signature service
 using SignInteractiveForm.ServiceReference1;

 //A reference to the Forms service
 using SignInteractiveForm.ServiceReference2;

 namespace SignInteractiveForm
 {
        class Program
        {
            static void Main(string[] args)
            {
                try
                {
                    //Because BLOB objects are used in both service references
                    //it is necessary to fully qualify the BLOB objects

                    //Retrieve the form -- invoke the Forms service
                    SignInteractiveForm.ServiceReference2.BLOB formData = GetForm();

                    //Create a BLOB object associated with the Signature service
                    SignInteractiveForm.ServiceReference1.BLOB sigData = new SignInteractiveForm.ServiceReference1.BLOB();

                    //Transfer the byte stream from one Forms BLOB object to the
                    //Signature BLOB object
                    sigData.MTOM = formData.MTOM;

                    //Sign the Form -- invoke the Signature service
                    SignForm(sigData);
                }
                catch (Exception ee)
                {
                    Console.WriteLine(ee.Message);
                }
            }

            //Creates an interactive PDF form based on a XFA form - invoke the Forms service
            private static SignInteractiveForm.ServiceReference2.BLOB GetForm()
            {

                try
                {
                    //Create a FormsServiceClient object
                    FormsServiceClient formsClient = new FormsServiceClient();
                    formsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress("https://hiro-xp:8080/soap/services/FormsService?blob=mtom");

                    //Enable BASIC HTTP authentication
                    BasicHttpBinding b = (BasicHttpBinding)formsClient.Endpoint.Binding;
                    b.MessageEncoding = WSMessageEncoding.Mtom;
                    formsClient.ClientCredentials.UserName.UserName = "administrator";
                    formsClient.ClientCredentials.UserName.Password = "password";
                    b.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;
                    b.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;
                    b.MaxReceivedMessageSize = 2000000;
                    b.MaxBufferSize = 2000000;
                    b.ReaderQuotas.MaxArrayLength = 2000000;

                    //Create a BLOB to store form data
                    SignInteractiveForm.ServiceReference2.BLOB formData = new SignInteractiveForm.ServiceReference2.BLOB();
                    SignInteractiveForm.ServiceReference2.BLOB pdfForm = new SignInteractiveForm.ServiceReference2.BLOB();

                    //Specify an XML form data
                    string path = "C:\\Adobe\Loan.xml";
                    FileStream fs = new FileStream(path, FileMode.Open);

                    //Get the length of the file stream
                    int len = (int)fs.Length;
                    byte[] ByteArray = new byte[len];

                    fs.Read(ByteArray, 0, len);
                    formData.MTOM = ByteArray;

                    //Specify an XML form data
                    string path2 = "C:\\Adobe\LoanSigXFA.pdf";
                    FileStream fs2 = new FileStream(path2, FileMode.Open);

                    //Get the length of the file stream
                    int len2 = (int)fs2.Length;
                    byte[] ByteArray2 = new byte[len2];

                    fs2.Read(ByteArray2, 0, len2);
                    pdfForm.MTOM = ByteArray2;

                    PDFFormRenderSpec renderSpec = new PDFFormRenderSpec();
                    renderSpec.generateServerAppearance = true;

                    //Set out parameter values
                    long pageCount = 1;
                    String localValue = "en_US";
                    FormsResult result = new FormsResult();

                    //Render an interactive PDF form
                    formsClient.renderPDFForm2(
                        pdfForm,
                        formData,
                        renderSpec,
                        null,
                        null,
                        out pageCount,
                        out localValue,
                        out result);

                    //Write the data stream to the BLOB object
                    SignInteractiveForm.ServiceReference2.BLOB outForm = result.outputContent;
                    return outForm;
                }
                catch (Exception ee)
                {
                    Console.WriteLine(ee.Message);
                }
                return null;
            }

            //Sign the form -- invoke the Signature service
            private static void SignForm(SignInteractiveForm.ServiceReference1.BLOB inDoc)
            {

                try
                {
                    //Create a SignatureServiceClient object
                    SignatureServiceClient signatureClient = new SignatureServiceClient();
                    signatureClient.Endpoint.Address = new System.ServiceModel.EndpointAddress("https://hiro-xp:8080/soap/services/SignatureService?blob=mtom");

                    //Enable BASIC HTTP authentication
                    BasicHttpBinding b = (BasicHttpBinding)signatureClient.Endpoint.Binding;
                    b.MessageEncoding = WSMessageEncoding.Mtom;
                    signatureClient.ClientCredentials.UserName.UserName = "administrator";
                    signatureClient.ClientCredentials.UserName.Password = "password";
                    b.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;
                    b.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;
                    b.MaxReceivedMessageSize = 2000000;
                    b.MaxBufferSize = 2000000;
                    b.ReaderQuotas.MaxArrayLength = 2000000;

                    //Specify the name of the signature field
                    string fieldName = "form1[0].grantApplication[0].page1[0].SignatureField1[0]";

                    //Create a Credential object
                    Credential myCred = new Credential();
                    myCred.alias = "secure";

                    //Specify the reason to sign the document
                    string reason = "The document was reviewed";

                    //Specify the location of the signer
                    string location = "New York HQ";

                    //Specify contact information
                    string contactInfo = "Tony Blue";

                    //Create a PDFSignatureAppearanceOptions object
                    //and show date information
                    PDFSignatureAppearanceOptionSpec appear = new PDFSignatureAppearanceOptionSpec();
                    appear.showDate = true;

                    //Sign the PDF document
                    SignInteractiveForm.ServiceReference1.BLOB signedDoc = signatureClient.sign(
                        inDoc,
                        fieldName,
                        myCred,
                        HashAlgorithm.SHA1,
                        reason,
                        location,
                        contactInfo,
                        appear,
                        true,
                        null,
                        null,
                        null);

                    //Populate a byte array with BLOB data that represents the signed form
                    byte[] outByteArray = signedDoc.MTOM;

                    //Save the signed PDF document
                    string fileName = "C:\\Adobe\LoanXFASigned.pdf";
                    FileStream fs2 = new FileStream(fileName, FileMode.OpenOrCreate);

                    //Create a BinaryWriter object
                    BinaryWriter w = new BinaryWriter(fs2);
                    w.Write(outByteArray);
                    w.Close();
                    fs2.Close();
                }

                catch (Exception ee)
                {
                    Console.WriteLine(ee.Message);
                }
            }
        }
 }

Tjänster som börjar med bokstaven I skapar ogiltiga proxyfiler services-starting-with-the-letter-i-produce-invalid-proxy-files

Namnet på vissa AEM Forms-genererade proxyklasser är felaktigt när Microsoft .Net 3.5 och WCF används. Problemet inträffar när proxyklasser skapas för IBMFilenetContentRepositoryConnector, IDPSchedulerService eller någon annan tjänst vars namn börjar med bokstaven I. Namnet på den genererade klienten om det finns IBMFileNetContentRepositoryConnector är till exempel BMFileNetContentRepositoryConnectorClient. Bokstaven I saknas i den genererade proxyklassen.