System-to-System Developer s Guide

Transcription

1 System-t-System Develper s Guide Revisin: 3.1 Date: December 16, 2003 PURPOSE This dcument describes the extensin f the smbxml (small and medium business extensible Markup Language) integratin functinality t supprt the bi-directinal exchange f business data between NetSuite prducts and third-party systems. smbxml was develped t facilitate the exchange f business infrmatin between trusted, third-party, XMLenabled, business applicatins and the NetSuite prduct family. smbxml was riginally implemented as a user initiated exchange f XML data via flat-file exprt and imprt. This was perfrmed by selecting the file t imprt thrugh the standard NetSuite web-brwser interface, and is referred t as smbxml UI Imprt. System-t-System (s2s) integratin enables trusted systems t add, update and query data in an integrated NetSuite accunt in real-time, r in batch, withut user interventin. Mst ften this is dne in real-time, in respnse t an event ccurring in the integrated third-party system (e.g.: a purchase being made in a third-party e-cmmerce applicatin, that sends transactin, custmer and item infrmatin t the NetSuite prduct regarding the sale). System-t-System integratin supprts the same recrds and actins as the smbxml UI Imprt capability, available in the standard user interface.

2 TABLE OF CONTENTS TABLE OF CONTENTS OVERVIEW CUSTOMERS AND APPLICATION PROVIDERS DOCUMENT ROADMAP IMPLEMENTATION OVERVIEW SUPPORTED PLATFORMS AND NETSUITE DEVELOPMENT SUPPORT ARCHITECTURE Tw-Way Secure Scket Layer (SSL) Additinal Certificate Verificatin Data Exchange Steps PRE-IMPLEMENTATION CHECKLIST Integratin Partner will Prvide NetSuite NetSuite will Prvide Integratin Partner IMPLEMENTATION CYCLE SETUP CLIENT CERTIFICATE JAVA PLATFORM MICROSOFT DEVELOPMENT PLATFORM IMPLEMENTATION DETAILS SMBXML Related Dcumentatin DTD Elements Many t One URLS AND HOSTNAMES Pst URL SINGLE SIGNON ACCOUNT MAPPING DO I NEED SINGLE SIGNON? THE PROBLEM THE SOLUTION FURTHER RESOURCES AND DOCUMENTATION USER INTERFACE OPTIONS APPENDIX A REFERENCES APPENDIX B JAVA CODE SAMPLE APPENDIX C MICROSOFT.NET C# CODE SAMPLE Cnfidential Material 2 f 19

3 1 OVERVIEW 1.1 CUSTOMERS AND APPLICATION PROVIDERS Generally, there are tw types f integratin partners, custmers and applicatin prviders. Custmers are themselves users f a NetSuite prduct, and are interested in integrating their NetSuite applicatin data with that f an external, third-party, applicatin s data. An example wuld be a NetSuite custmer that ran an external, custm, e-cmmerce applicatin, that feeds sales infrmatin (transactins, custmers, items, etc.) int their NetSuite accunt. Applicatin Prviders are prviders f applicatins and services t end-custmers, wh are themselves custmers f NetSuite. Applicatin prviders are interested in integrating their custmers applicatin data, stred within the applicatin prvider s datacenter, with their custmers NetSuite data. An example wuld be a thirdparty Pint -f-sale (POS) prvider, that wanted t transmit their custmers sales infrmatin (transactins, custmer, items, etc.) int the NetSuite accunts f their end-custmers. In this scenari, the applicatin prvider acts as an agent n behalf f ur mutual custmer. Thrughut this dcument, custmers and applicatin prviders will be called integratin partners, cllectively. Befre prceeding with this dcument, yu shuld knw whether yu are a custmer r an applicatin prvider. Fr mre explanatin n the difference between custmers and applicatin prviders, please refer t the Custmer v. Applicatin Prvider dcument available with the NetSuite Develper Prgram Technical Dcumentatin, r with yur NetSuite Accunt Manager. 1.2 DOCUMENT ROADMAP NetSuite s System-t-System security mdel uses several technlgies and methds t ensure secure cmmunicatin and enfrce apprpriate integratin partner access t user data. The fllwing sectins will describe: Implementatin verview that includes platfrms supprted by NetSuite, the System-t-System architecture, an implementatin checklist, and an verview f the implementatin cycle. Step-by-step instructins fr the creatin f a keystre cntaining the client certificate Overview f smbxml and the DTD elements specific t System-t-System data exchange Brief verview f the NetSuite Single Signn (SSO) technlgy used t map accunts between systems, and enable applicatin prvider access t a user s NetSuite data User interface ptins relevant t System-t-System integratin Cnfidential Material 3 f 19

4 2 IMPLEMENTATION OVERVIEW 2.1 SUPPORTED PLATFORMS AND NETSUITE DEVELOPMENT SUPPORT While ur integratin technlgy t establish System-t-System cnnectivity is based n standards and can be used frm any develpment platfrm, NetSuite fficially supprts the fllwing tw develpment platfrms. Java platfrm Micrsft.NET platfrm If yu re using ne f these platfrms, NetSuite will be able t prvide a cmmand line driven test client that is designed t test SSL cnnectivity t NetSuite, pst smbxml dcuments t NetSuite, and t serve as an example fr the develpment f the integratin partner s applicatin cde. The tl includes the surce cde. Currently, the primary develpment expertise f NetSuite Prfessinal Services are with the abve mentined platfrms, and Prfessinal Services ability t advise and cnsult will be strngest fr integratin partners whse implementatin is in these platfrms. If the client applicatin t be implemented uses a different language r platfrm, as lng as this envirnment supprts tw-way SSL cmmunicatins, there shuld nt be any prblems in implementatin since there are n NetSuite prprietary libraries that need t be used. 2.2 ARCHITECTURE TWO-WAY SECURE SOCKET LAYER (SSL) Put simply, System-t-System integratin allws data (in the frm f an smbxml dcument) t be psted t, r queried frm, NetSuite accunts via an HTTPS pst. NetSuite uses a Tw-Way Secure Scket Layer authenticatin methdlgy, fr System-t-System cmmunicatins, that ensures that bth parties are wh they claim t be. The client is required t validate NetSuite s server certificate, and t prvide a client certificate in rder t authenticate themselves t NetSuite. NetSuite s Tw-Way Secure Scket Layer (SSL) uses industry standard 128-bit SSL encryptin, as well as certificate hash cmparisn. Server authenticatin takes place ver an SSL cnnectin initiated with NetSuite s key pair signed by a mutually trusted key signer (in this case RSA). The certificate-based client authenticatin uses a client generated key pair, the public key f which is signed by and pssessed by NetSuite. Fr details n certificate-based SSL, please see Appendix A f this dcument. Cncisely, Tw-Way SSL allws fr the fllwing: The Client verifies that the Server is wh it claims t be. The Server verifies that the Client is wh it claims t be ADDITIONAL CERTIFICATE VERIFICATION As a further check n authenticatin, nce the XML request dcument is received, NetSuite perfrms secndary validatin f the client certificate by cmparing a hash f the certificate t a previusly stred hash, taken during the signing phase. This secnd validatin f the certificate is perfrmed t ensure that the certificate being presented matches identically the certificate riginally prvided by the partner DATA EXCHANGE STEPS 1. integratin partner system generates a valid smbxml dcument Cnfidential Material 4 f 19

5 2. integratin partner pens an HTTPS cnnectin t the NetSuite smbxml server 3. during the SSL handshake a. the integratin partner verifies NetSuite s identity by validating the NetSuite server certificat e, signed by RSA b. the NetSuite server verifies the identity f the integratin partner by requesting a client -side certificate, signed by NetSuite c. the smbxml server returns a symmetric key, encrypted using the integratin partner s public key, used t establish SSL cmmunicatin d. SSL is established 4. partner system transmits smbxml dcument t NetSuite in the bdy f an HTTP Pst 5. the smbxml server perfrms secndary validatin f the certificate, by cmparing a hash f the certificate t a previusly stred hash f the certificate 6. the smbxml server parses the smbxml dcument and determines whether the partner system has the apprpriate permissins t perfrm the requested actin(s) in the accunt specified 7. the smbxml server prcesses the requests and returns the results in the bdy f an HTTP Respnse with: e. any apprpriate success r errr messages f. the results f any query requests 2.3 PRE-IMPLEMENTATION CHECKLIST Prir t beginning develpment and testing f XML data transmissin, NetSuite and the integratin partner will exchange certificates, public keys, URLs and partner IDs INTEGRATION PARTNER WILL PROVIDE NETSUITE certificate signing request (CSR) signed by NetSuite, fr establishing client authenticatin 1024-bit public key fr use in Single Signn (applicatin prviders nly) cmpany name used as the partneraccunt, discussed belw under DTD Elements (custmers nly) NETSUITE WILL PROVIDE INTEGRATION PARTNER unique partner ID used during System-t-System and Single Signn cmmunicatin, discussed belw under DTD Elements and Single Signn signed client certificate the signed client certificate signing request NetSuite signing certificate the NetSuite certificate used t sign the client CSR RSA signing certificate the public RSA certificate that signed ur server certificate, discussed abve under the Architecture Overview, SSL handshake sectin pst URL the prductin pst URL, used by the client t pst smbxml dcuments t NetSuite 2.4 IMPLEMENTATION CYCLE The fllwing wrkflw details the implementatin steps integratin partners undertake, and the NetSuite rganizatins respnsible fr each step. Cnfidential Material 5 f 19

6 Fllwing is a detailed list f steps: 1. Create a sample smbxml dcument. Ensure that it is valid against the current versin f the smbxml DTD. Ensure that it can be imprted int NetSuite using the smbxml UI Imprt (Transactins > Other > Imprt XML Dcument). Cnfidential Material 6 f 19

7 2. Setup certificates fr Tw-way SSL cmmunicatins. Nte that an integratin partner may register mre than ne certificate with NetSuite in the event that the integratin partner is using multiple servers fr data exchange with NetSuite, althugh this is nt required. 3. Write and test the necessary cde in rder t pen a SSL cnnectin. Please see Appendix B fr cde samples. Ensure that the sample smbxml dcument used abve is used fr testing. Nte that smbxml dcuments psted via System-t-System have a required header, discussed belw in the DTD Elements sectin, that is ptinal during an smbxml UI Imprt. 4. Write yur applicatin specific cde t generate smbxml dcuments and send them t NetSuite using the SSL cnnectin. 5. Implement Single Signn Accunt Mapping If yu are an applicatin prvider, this is a mandatry step. If yu are a custmer, this step is ptinal, unless yu want t prvide Single Signn capability t yur emplyees. 6. Arrange fr NetSuite Prfessinal Services t sign-ff n yur implementatin. Cnfidential Material 7 f 19

8 3 SETUP CLIENT CERTIFICATE As discussed previusly, NetSuite s Tw-Way Secure Scket Layer authenticatin uses public/private key technlgy t authenticate clients against NetSuite servers and als t authenticate NetSuite servers t cnnecting clients. This authenticatin uses a client generated key pair the public key f which is signed by and pssessed by NetSuite. Authenticatin takes place ver an SSL cnnectin initiated with NetSuite s key pair signed by a mutually trusted key signer (in this case RSA). The SSL prtin f this prcess guarantees t the client that NetSuite is NetSuite and the NetSuite authenticatin prtin f this prcess guarantees t NetSuite that the client is the client wh they claim t be. There are three certificates that are used in NetSuite s Tw-Way Secure Scket Layer authenticatin: 1. the integratin partner s client certificate, signed by us (which is the signed CSR) 2. the NetSuite certificate used t sign yur CSR (NLCACert4Partners.der) 3. the RSA certificate used t sign ur server certificate (RSASignedCERT.cer) The certificates frm 1 and 2 abve are stred within yur keystre the same ne that yu used t generate the CSR in the first place. A keystre cntains yur public and private key-pair used t create the CSR, as well as varius certificates. The fllwing sectins describe the cnstructin and use f keystres in greater detail. The RSA certificate, frm 3, is used at the beginning f an SSL handshake, when yu are verifying ur server certificate, t assure yurselves that we are wh yu think we are. Yu may btain the RSA certificate directly frm ur site (using a brwser and by clicking the IE security lck icn), frm RSA directly, r wait fr us t send it t yu (we always send a cpy f all three certificates when replying t CSRs). The fllwing steps utline the prcess in detail. Nte that these steps use a fictitius cmpany named Client, Inc. Yu shuld be able t use these cmmands exactly as they appear by replacing the example references t Client, Inc, and its related passwrd and cmpany infrmatin. If the integratin partner has mre than ne NetSuite accunt that they need t enable system-t-system access fr, they have the fllwing ptins: They may register a certificate fr each NetSuite accunt. They may use a single certificate acrss all accunts. Nte that unlike server certificates, a client certificate is nt bund t a specific physical machine, and therefre, a certificate can be cpied t ther machines. 3.1 JAVA PLATFORM When using the Java platfrm, creating a client certificate is best achieved by using Java s native supprt fr certificates. Fllwing is a detailed list f steps required t create a certificate, get it signed by NetSuite, and install the certificate. Step 1: Install the Java 2 Platfrm, Standard Editin JDK versin 1.4 r higher Yu will need the keytl prgram that cmes with this versin f the JDK in rder t manage keystres. Once the JDK has been installed, and the bin directry f the JDK has been added t the system path, yu shuld be able t run the keytl cmmand at the cmmand prmpt. Step 2: Generate a new public/private key pair in a new keystre as fllws Cnfidential Material 8 f 19

9 A new public/private key pair is generated in a new keystre. The keystre shuld be stred in a secure lcatin. In the fllwing example, a 2048-bit RSA private/public key pair with an alias f client and a passwrd f mykeypass is generated and stred in the file client.keystre, which is prtected with the passwrd mystrepass. keytl -genkey -dname "cn=client.cm, u=engineering, =Client, c=us, st=califrnia" -alias "client" -keypass mykeypass -keystre "client.keystre" - strepass mystrepass -keyalg "RSA" -keysize 2048 The dname parameter specifies the fllwing. If yu mit this parameter, the tl will prmpt yu fr this infrmatin. Name CN O OU C ST Descriptin Valid dmain name fr yur cmpany Cmpany name Organizatinal Unit Cuntry State Step 3: Create a Certificate Signing Request (CSR) The public key generated abve needs t be signed by a Certificate Authrity (CA). The new key pair is used t generate a Certificate Signing Request r CSR. A CSR is a file that is sent t the certificatin authrity fr signing; it cntains the public key that needs t be signed in a special frmat. Nte that the CA in this case is NetSuite. keytl -keystre client.keystre -keypass mykeypass -strepass mystrepass - alias client -certreq -file client.csr The abve cmmand uses a keystre named client.keystre with a passwrd f mykeypass t generate a CSR named client.csr fr the key with an alias f client. Step 4: the CSR t NetSuite NetSuite will act as the CA and sign the certificate. It will als extract a hash f the certificate and stre it internally s that a secndary check can be perfrmed n all incming requests. The shuld be sent t certsignreq@netsuite.cm with the CSR file as an attachment. It shuld include the fllwing: Subject: Certificate Signing Request fr <Cmpany Name> Bdy: Partner ID: The partner ID assigned by NetSuite NetSuite Accunt Number(s): The accunts that require System-t-System access. May include a prductin accunt and a test accunt. Yu can btain yur NetSuite accunt number as fllws: NetSuite Hme > Set Up Synchrnizatin (Under Settings Prtlet) > Accunt number is displayed in text bx. Partner Accunt Name: Prvide a lgical name that yu wuld like yur NetSuite accunt prvided abve t be referred by (custmers nly). Fr example, if yur cmpany name is ABC Crp, yu might have ABC_Prductin and ABC_Test as yur accunt names. Slutin prviders d nt prvide a Partner Accunt, unless they have made special arrangements with Prfessinal Services t manually cnfigure accunt mapping; therwise, Partner Accunt is determined dynamically, as established via Single Signn Accunt Mapping, discussed in the Single Signn sectin. The Certificate Signing Request as an attachment. Cnfidential Material 9 f 19

10 Step 5: Update the keystre with the NetSuite certificate and the signed certificate NetSuite will yu the signed client certificate as well as NetSuite s self-signed, signing certificate (named NLCACert4Partners.der), that was used t sign yur client certificate. Yu will need t imprt bth f these certificates int yur keystre. First imprt NetSuite s signing certificate int yur keystre as a trusted CA. When asked if yu want t trust this certificate, answer yes. In the fllwing example, the NetSuite certificate named NLCACert4Partners.der is imprted int the keystre named client.keystre as a trusted CA. keytl -keystre client.keystre -strepass mystrepass -alias CA -keypass mykeypass -imprt -file NLCACert4Partners.der Yu will see a respnse similar t the fllwing, and will be prmpted t trust the certificate. Owner: ADDRESS=dwilliams@netsuite.cm, O="NetSuite, Inc.", ST=Califrnia, L=San Mate, C=US, CN=system.NetSuite.cm Issuer: ADDRESS=dwilliams@netsuite.cm, O="NetSuite, Inc.", ST=Califrnia, L=San Mate, C=US, CN=system.NetSuite.cm Serial number: 1 Valid frm: Fri Aug 11 08:53:00 PDT 2000 until: Mn Aug 09 08:53:00 PDT 2010 Certificate fingerprints: MD5: 65:17:3D:5B:3C:F4:AB:45:D8:CA:EC:E2:BC:CC:9D:51 SHA1: ED:60:C9:73:17:DC:13:1B:AB:0E:41:7C:28:18:DE:99:51:81:71:DB Trust this certificate? [n]: y Certificate was added t keystre Next, imprt the signed client certificate int yur keystre. The keytl will check the signatries f the certificate t ensure that their signatures can be validated. In this case, since the NetSuite certificate (public key) is already in the same keystre, this validatin is successful. In the fllwing example, the signed certificate named client.der is imprted int the keystre named client.keystre with a passwrd f mystrepass under the alias client with a passwrd f mykeypass. keytl -keystre client.keystre -strepass mystrepass -alias "client" - keypass mykeypass -imprt -file client.der 3.2 MICROSOFT DEVELOPMENT PLATFORM This sectin details hw t setup certificates using OpenSSL that are intended fr use primarily within the Micrsft.NET platfrm. These directins can als be used t setup certificates fr use with ther Micrsft develpment platfrm such as Active Server Pages (ASP), Visual C++, Visual Basic, as well as ther external Micrsft Windws based develpment platfrms (fr example, Delphi) althugh these platfrms are nt fficially supprted by NetSuite. Please see sectin 2.1 entitled Supprted Platfrms and NetSuite Develpment Supprt fr mre details n platfrms supprted by NetSuite. Fllwing is a detailed list f steps using OpenSSL t create a certificate, getting it signed by NetSuite, and installing the certificate. Step 1: Install OpenSSL Dwnlad the latest release f OpenSSL in ne f the fllwing frmats and install. Nte that NetSuite recmmends installing Cygwin as it is the quickest and mst reliable ptin. Install the latest versin f Cygwin frm and ensure that the OpenSSL ptin is checked befre installing. This is the recmmended ptin as Cygwin cmes with the required cnfiguratin files fr OpenSSL. Cnfidential Material 10 f 19

11 Install a pre-cmpiled versin f OpenSSL in executable frmat fr Windws. Nte that the fficial site has nly the surce and des nt cntain a pre-cmpiled versin fr Windws. Find a mirrr site such as t dwnlad the zip file that cntains penssl.exe and a cuple f related DLLs. This requires setting up an OpenSSL cnfiguratin file that yu need t find elsewhere n the Internet. Once installed, ensure that these executables are in yur system path. Step 2: Create a Certificate Signing Request (CSR) Generate a key pair with a RSA 1024 bit private key, and a Certificate Signing Request (CSR) as fllws. Nte that in this example, the private key is stred in client.key and the certificate expires in 10 years. Yu will als be prmpted fr a passwrd t prtect yu private key. penssl req -new -keyut client.key -ut client.csr -days 3650 A CSR is a file that is sent t the certificatin authrity fr signing; it cntains the public key that needs t be signed in a special frmat. Nte that the CA in this case is NetSuite. As part f this request, yu will be prmpted fr infrmatin that will be inserted int yur certificate. Fllwing is a sample lg that illustrates this infrmatin. Generating a 1024 bit RSA private key writing new private key t 'client.key' Enter PEM pass phrase: Verifying - Enter PEM pass phrase: Yu are abut t be asked t enter infrmatin that will be incrprated int yur certificate request. What yu are abut t enter is what is called a Distinguished Name r a DN. There are quite a few fields but yu can leave sme blank Fr sme fields there will be a default value, If yu enter '.', the field will be left blank Cuntry Name (2 letter cde) [AU]:US State r Prvince Name (full name) [Sme-State]:CA Lcality Name (eg, city) []:San Mate Organizatin Name (eg, cmpany) [Internet Widgits Pty Ltd]:XYZ Inc Organizatinal Unit Name (eg, sectin) []:Engineering Cmmn Name (eg, YOUR name) []:XYZ Inc Address []:inf@xyz.cm Step 3: the CSR t NetSuite NetSuite will act as the CA and sign the certificate. It will als extract a hash f the certificate and stre it internally s that a secndary check can be perfrmed n all incming requests. The shuld be sent t certsignreq@netsuite.cm with the CSR file as an attachment. It shuld include the fllwing: Subject: Certificate Signing Request fr <Cmpany Name> Bdy: Partner ID: The partner ID assigned by NetSuite Cnfidential Material 11 f 19

12 NetSuite Accunt Number(s): The accunts that require System-t-System access. May include a prductin accunt and a test accunt. Yu can btain yur NetSuite accunt number as fllws: NetSuite Hme > Set Up Synchrnizatin (Under Settings Prtlet) > Accunt number is displayed in text bx. Partner Accunt Name: Prvide a lgical name that yu wuld like yur NetSuite accunt prvided abve t be referred by (custmers nly). Fr example, if yur cmpany name is ABC Crp, yu might have ABC_Prductin and ABC_Test as yur accunt names. Slutin prviders d nt prvide a Partner Accunt, unless they have made special arrangements with Prfessinal Services t manually cnfigure accunt mapping; therwise, Partner Accunt is determined dynamically, as established via Single Signn Accunt Mapping, discussed belw. The Certificate Signing Request as an attachment. Step 4: Add NetSuite certificate and the signed certificate t Certificate Stre NetSuite will yu the signed client certificate (named client.pem in this example), as well as NetSuite s selfsigned certificate (named NLCACert4Partners.der), that was used t sign yur client certificate. Duble click n the NLCACert4Partners.der certificate t install it as a trusted rt CA certificate under the Trusted Rt Certificatin Authrities stre fr the current user lgged int Windws as fllws: Click Install Certificate Click Next in the Welcme t the Certificate Imprt Wizard dialg bx Select the Autmatically select the certificate stre based n type f certificate radi buttn and click Next Click Finish Next, cnvert yur certificate int the PKCS12 frmat by executing the fllwing OpenSSL cmmand. The PKCS12 frmat is a certificate stre that stres bth yur signed certificate and private key in ne file. penssl pkcs12 -exprt -clcerts -in client.pem -inkey client.key -ut client.p12 Duble click n the client.p12 file t install the certificate in the Persnal Certificate Stre under the current user lgged int Windws as fllws: Click Next in the Welcme t the Certificate Imprt Wizard dialg bx Click Next in the File Imprt screen Check the Mark this key as exprtable check bx and click Next Select the Autmatically select the certificate stre based n type f certificate radi buttn and click Next Click Finish Yu can verify that these certificates were imprted successfully by using Internet Explrer and selecting Tls > Internet Optins > Cntent > Certificates, and lking at the Persnal and Trusted Rt Certificatin Authrities tabs. Cnfidential Material 12 f 19

13 4 IMPLEMENTATION DETAILS 4.1 SMBXML RELATED DOCUMENTATION smbxml is used fr all cmmunicatins between the integratin partner and NetSuite. The fllwing smbxmlrelated dcumentatin may be fund with the NetSuite Develper Prgram Technical Dcumentatin n the NetSuite website ( > Partners > Develper Prgram). DTD release ntes smbxml Develper s Guide example imprt files custmer v. applicatin prvider dcument methdlgy dcuments DTD and release nte archive The current DTD fr smbxml is available at the fllwing URL: where X_XX represents the current DTD revisin number DTD ELEMENTS The smbxml DTD is used fr bth smbxml UI Imprt, using the standard web-based interface, as well as fr System-t-System data exchange. In rder t supprt System-t-System smbxml, there have been tw minr changes t the smbxml DTD. The existing <smbxml> element has been mdified t include a header element, required fr System-t-System data exchange, but which remains ptinal/ignred during smbxml UI imprt. The new header element, referenced in the <smbxml> element, has been added and defined as: <!ELEMENT smbxml ((header?, request+) respnse+)> <!ELEMENT header (partnerid, partneraccunt)> Where, partnerid is the integratin partner s unique identifier, as prvided t the partner by NetSuite (typically five numeric digits lng) partneraccunt is the integratin partner s unique accunt name fr the target cmpany t pst data t in NetSuite In the case f a custmer integratin, partneraccunt is the custmer s cmpany name, fr their wn accunt, and is prvided nce during the initial setup phase. Fr a custmer, the partnerid will always be the same value. In the case f an applicatin prvider integratin, partneraccunt is the applicatin prvider s cmpany name, fr the shared custmer accunt, and is dynamically determined based upn which mutual custmer s accunt they wish t pst data int.. Cnfidential Material 13 f 19

14 4.1.3 MANY TO ONE NetSuite accepts smbxml data frm multiple integrated partner accunts int a single NetSuite accunt. This supprts activities such as a NetSuite custmer aggregating cash sales, frm multiple external Webstres, int a single NetSuite accunt; r aggregating smbxml purchase rders and bills frm multiple exchanges, such as the Oracle exchange. NetSuite des nt currently supprt multiple accunts, frm the same integratin partner applicatin, integrating with a single NetSuite accunt. Fr example, while NetSuite supprts data frm Cmpany A in Partner 1, and Cmpany B in Partner 2, bth feeding int the same NetSuite accunt ACCT X, NetSuite des nt supprt data frm Cmpany A in Partner 1, and Cmpany B in Partner 1, bth feeding int the same NetSuite accunt ACCT X. Nte that the current implementatin als des nt prvide built in supprt t enable different integratin partners t elegantly share cmmn data in a single NetSuite accunt. This will be addressed in a frthcming specificatin. This new specificatin, Multi-Partner Synchrnizatin Supprt, will prvide a revisin system fr each smbxml accessible bject (custmer, vendr, inventry items, cash sale, invice, etc.) and will prevent integratin partners frm inadvertently verwriting anther partner s edits t recrds (r t thse made in the UI, fr that matter). 4.2 URLS AND HOSTNAMES POST URL The URL that is used t establish a System-t-System cnnectin with NetSuite and pst smbxml dcuments t is as fllws: The <partnerid> is the 5-digit identifier assigned by NetSuite t the partner/custmer fr partner mapping purpses. This is the same partnerid that is cntained within the smbxml header. The <partneraccunt> is the partner s unique cmpany accunt name fr the current request. This is the same partneraccunt that is cntained within the smbxml header. Fllwing is an example where the partner Id is and the partner accunt name is ShutterFly: Cnfidential Material 14 f 19

15 5 SINGLE SIGNON ACCOUNT MAPPING 5.1 DO I NEED SINGLE SIGNON? If yu are an applicatin prvider, yes. Fr an applicatin prvider, SSO is an essential part f System-t- System integratin. If yu are a custmer, n. Fr a custmer, SSO has nthing t d with System-t-System integratin. A custmer may still wish t implement SSO as it will allw custmer emplyees t mve frm the custmer applicatin int their NetSuite accunt withut the need t lgin (SSO is currently included with the System-t- System integratin setup and maintenance fees). If yu are an applicatin prvider, r yu are a custmer that is cnsidering implementing SSO fr its seamless lgin capabilities, then read n further in this sectin; therwise yu may mve n t the next sectin. 5.2 THE PROBLEM In rder fr an integratin partner t pst data int a NetSuite accunt, the partner must identify the target accunt in NetSuite. NetSuite des nt want integratin partners t have t maintain lists f NetSuite s internal accunt identifiers. Cnsequently, NetSuite requires the integratin partner t identify the target cmpany with a unique identifier f their wn chsing, passed via the partneraccunt element f the smbxml dcument header element as discussed in sectin NetSuite then maintains a mapping between the integratin partner cmpany identifiers, and NetSuite s wn internal identifiers. In the case f custmers, there is nly ever ne identifier, that f the custmer itself. In the case f applicatin prviders, there may be many shared cmpanies, each with their wn unique identifiers in bth the applicatin prvider system and within NetSuite. Fr custmers, NetSuite enters the mapping table entries manually; this wuld be prhibitive in the case f applicatin prviders, and, therefre, an autmated slutin is used: Single Signn Accunt Mapping. 5.3 THE SOLUTION NetSuite s Single Signn (SSO) technlgy was riginally develped t allw shared custmers t mve between trusted, integrated applicatins, withut the need t re-authenticate (i.e. re-present accunt/passwrd infrmatin). NetSuite s Single Signn technlgy uses RSA cryptgraphy t exchange infrmatin securely, and establish trust between NetSuite and its integratin partners. Trust and accunt mapping are established when the applicatin prvider Web applicatin redirects the shared custmer t an XML linking prtal. This initial accunt mapping and trust must be initiated by the administratr f the NetSuite accunt. This ensures that smbxml data exchange is a cnscius decisin by the NetSuite accunt administratr. Once the accunt mapping is established, XML exchanges between the applicatin prvider and NetSuite are permitted n behalf f the shared custmer. 5.4 FURTHER RESOURCES AND DOCUMENTATION The redirect string may be generated using a java library prvided by NetSuite, r thrugh partner-specific tls develped t cnstruct a Single Signn cmpliant redirect string. Using the NetSuite tls will reduce csts and develpment time assciated with testing a new implementatin f tken generatin and encryptin. Cmplete dcumentatin n NetSuite s SSO technlgy can be fund in NetSuite s Single Signn Develper s Guide, available frm yur NetSuite Accunt Manager r Prfessinal Services Manager. The SSO integratin utilities and sftware license will nly be prvided t integratin partners that have signed NetSuite s Mutual Nn- Disclsure Agreement. In rder t use the SSO integratin utilities, the integratin partner must agree t the terms f the Single Signn license agreement. Cnfidential Material 15 f 19

16 6 USER INTERFACE OPTIONS Single Signn may be turned ff, fr thse custmers that wish t nly enable smbxml data exchange, frm the Setup tab > Accunting sub-sectin > Set Up Accunting link > Web sub-tab, by clearing the Allw Sign On Frm Partners checkbx. smbxml data exchange may be turned ff, n a integratin partner by partner basis, frm the Setup tab > Imprt/Exprt sub-sectin > Set Up XML Imprt link > by clearing the Allw XML Frm Partners checkbx fr the apprpriate partner. Nte that this sectin and the crrespnding checkbxes will nly appear if there are partners that have been enabled fr smbxml data exchange fr the accunt in questin. Cnfidential Material 16 f 19

17 APPENDIX A REFERENCES Hw SSL Wrks, Intrductin t Public-Key Cryptgraphy, Set Up a Certificatin Authrity fr Java-based Systems, X.509 Certificates and Certificate Revcatin Lists (CRLs), Implementing Web Site Client Authenticatin Using Digital IDs, Cnfidential Material 17 f 19

18 APPENDIX B JAVA CODE SAMPLE Fllwing is a Java cde sample taken frm the NetSuite smbxmlpst tl that illustrates hw a tw-way SSL cnnectin is established using a keystre. imprt javax.net.ssl.*; imprt java.net.*; imprt java.security.*; imprt java.security.cert.*; // Private key passwrd String keypasswrd = "mykeypass"; // Keystre passwrd String strepasswrd = "mystrepass"; // Fully qualified path t keystre file String keystrename = "my.keystre"; // Read the keystre file and lad the keystre KeyStre keystre = null; InputStream keystrestream = new ByteArrayInputStream( base64decde( keystrename.getbytes() )); keystre = KeyStre.getInstance("JKS"); keystre.lad(keystrestream, strepasswrd.tchararray()); // Initialize the KeyManagerFactry KeyManagerFactry keymanagerfactry = KeyManagerFactry.getInstance("SunX509"); keymanagerfactry.init(keystre, keypasswrd.tchararray()); // Create and initialize SSLCntext and generate randm number SSLCntext ssl = SSLCntext.getInstance("SSL"); SecureRandm sr = new SecureRandm(); sr.nextint(); ssl.init(keymanagerfactry.getkeymanagers(), null, sr); // Open HTTP cnnectin URL url = new URL(m_sUrl); HttpURLCnnectin cnn = (HttpURLCnnectin) url.pencnnectin(); // Set cnnectin t include SSL cntext SSLScketFactry sf = ssl.getscketfactry(); ((javax.net.ssl.httpsurlcnnectin)cnn).setsslscketfactry (sf); // Set ther cnnectin parameters and lad request data... // Cnnect and push the request int the cnnectin scket cnn.cnnect(); // This methd used abve decdes the given byte[] using the // base64-encding specified in RFC-2045 (Sectin 6.8). public final static byte[] base64decde(byte[] data) {... } Cnfidential Material 18 f 19

19 APPENDIX C MICROSOFT.NET C# CODE SAMPLE Fllwing is a Micrsft.NET C# cde sample taken frm the NetSuite smbxmlpst tl that illustrates hw a tw-way SSL cnnectin is established in the.net platfrm. // NetSuite URL t pst t string url = " HttpWebRequest req; HttpWebRespnse res; // Create request bject that cnnects t NetSuite req = (HttpWebRequest) WebRequest.Create( url ); req.methd = "POST"; req.cntenttype = "text/xml"; // The path t the certificate. string certfilepath = "C:\\client.der"; // Lad the certificate int an X509Certificate bject. X509Certificate x509cert = ); // Add certificate t request req.clientcertificates.add( x509cert ); // Read smbxml file and write cntents t request stream StreamReader infilereader = new StreamReader("c:\\queryAllSalesOrders.xml"); StreamWriter reqwriter = new StreamWriter( req.getrequeststream() ); string sline = null; while ( ( sline = infilereader.readline() )!= null ) { reqwriter.writeline( sline ); } infilereader.clse(); reqwriter.clse(); // Get respnse res = (HttpWebRespnse) req.getrespnse(); System.Cnsle.Out.WriteLine( "Status Cde: " + res.statuscde ); StreamReader respnsereader = new StreamReader(res.GetRespnseStream(), Encding.ASCII); // Put the results in a string and print t cnsle System.Cnsle.Out.WriteLine("\n"); strresult = respnsereader.readtend(); respnsereader.clse(); Cnsle.WriteLine(strResult); Cnfidential Material 19 f 19