Preview only show first 10 pages with watermark. For full document please download

Integrator Guide 2012-12-08

   EMBED


Share

Transcript

Integrator Guide ■ SAP BusinessObjects Information Steward 4.1 Support Pack 1 (14.1.1.0) 2012-12-08 Copyright © 2012 SAP AG. All rights reserved.SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, SAP HANA and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries.Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business Objects is an SAP company.Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL Anywhere, and other Sybase products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Sybase, Inc. Sybase is an SAP company. Crossgate, m@gic EDDY, B2B 360°, B2B 360° Services are registered trademarks of Crossgate AG in Germany and other countries. Crossgate is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. 2012-12-08 Contents 3 Chapter 1 Web service support...............................................................................................................5 1.1 1.2 1.2.1 1.2.2 Overview..................................................................................................................................5 Chapter 2 Using SAP BusinessObjects Information Steward as a web service provider........................9 2.1 2.2 2.2.1 2.2.2 2.3 2.3.1 2.3.2 2.3.3 Introduction..............................................................................................................................9 Chapter 3 Troubleshooting....................................................................................................................29 3.1 Web Services log...................................................................................................................29 Chapter 4 Appendix...............................................................................................................................31 4.1 4.2 4.3 4.4 4.5 4.5.1 4.5.2 4.5.3 4.5.4 4.5.5 is-common.wsdl.....................................................................................................................31 Web Services technologies......................................................................................................6 WSDL......................................................................................................................................6 XSD.........................................................................................................................................7 Using a WSDL file..................................................................................................................12 Common Web Services.........................................................................................................13 Metapedia Web Services.......................................................................................................19 Security considerations..........................................................................................................24 Configuring the Web Services security policy........................................................................24 Enabling and disabling the default security policy....................................................................25 Configuration options.............................................................................................................25 is-common.xsd.......................................................................................................................33 Metapedia_WebServices.wsdl...............................................................................................34 Metapedia_Services.xsd........................................................................................................36 Security configuration files.....................................................................................................37 policy.properties.....................................................................................................................37 default_server.keystore..........................................................................................................39 default_client.keystore...........................................................................................................39 https_policy.xml.....................................................................................................................40 axis2.xml................................................................................................................................40 2012-12-08 Contents Index 4 43 2012-12-08 Web service support Web service support 1.1 Overview The SAP BusinessObjects information Steward Integrators Guide allows web service developers to develop their own interface to the Metpedia component of Information Steward using a programming language of their choice. Currently, maintaining the Metapedia terms database is done using Information Steward Explorer. The access mechanism is SOAP (Simple Object Access Protocol). With the provided WSDL (Web Service Description Language) and / XSD (XML [Extensible Markup Language] Schema Documentation) interface files, login, session management, search and retrieval operations are possible. This SDK and documentation is intended for use by web service developers familiar with XSD, WSDL and web services. Metapedia search features When you use the Metapedia Web Service, search and retrieval of the following information is available: • • • • • • • • • • Term (the Terms that are approved for retrieval) Term description Author Last modified date URL of the Metapedia term Synonyms Categories Associated keywords Term relationships Custom Attributes Metapedia Web Service session management features include the ability to specify the maximum number of terms to retrieve, the ability to specify the index value, and pagination. Advanced search features include the use of a wildcard character such as * (for multiple characters) and ? (for single characters). The Common Web Service features include login that supports several SAP BOE authentication methods by using authentication and session management so that authorized users can be logged in and out without compromising the security of the Business Intelligence platform generally, or unauthorized access to Information Steward specifically. For stateless operation and security, short-term sessionID 5 2012-12-08 Web service support tokens are used for each information request. Users who have View permissions set within Metapedia will be able to access the same information using the web service. Application possibilities With this SDK, developers can create widgets or plugins for Microsoft Office for Word, Outlook, PowerPoint, or Excel that allows their users to have quick and direct access to Metapedia business terms without having to switch back and forth from the Business Intelligence platform to Metapedia to their favorite program. About this guide This guide is divided into these sections: • Web service support - This is an overview of the technology used to facilitate access to the Information Steward Metapedia component. • Using SAP BusinessObjects Information Steward as a web service provider - How to use the Information Steward SDK, including how to log on, how use the Term search and retrieval options. • Configuring Web Services on the CMC. This is for the initial setup by administrators. 1.2 Web Services technologies Information Steward Metapedia Web Services use WSDL and XSD to define the interface rules. IS Common and Metapedia web services each have a corresponding WSDL and XSD file. The Metapedia interface is fully compliant with Web Services Interoperability (WS-I) Basic Profile 1.0, and supports support the standard Java Web Services technologies using SOAP, WSDL and XML. WSDL • • is-common.wsdl Metapedia_WebServices.wsdl XSD • • is-common.xsd Metapedia_Services.xsd 1.2.1 WSDL Web Services Description Language (WSDL) uses XML to define the structure, or schema definition of the XML document that is used in web services communication between client and server. The Metapedia SDK uses two WSDL definitions: 6 2012-12-08 Web service support • The Common Web Service WSDL provides a WS-Policy-based security infrastructure. Services include login, logout and validation services and logging. The is-common.wsdl file can be accessed from the URL: http://:/BOE/ISWebServices/Common?wsdl • The Metapedia Web Services WSDL provides search and retrieval functions. The Metapedia_WebServices.wsdl file can be accessed from the URL: http://:/BOE/ISWebServices/MetapediaService?wsdl Common Web Services The Common Web Services include login, logout, and ping. • login token or credentials (LoginToken returns the SessionId) • logout (requires the SessionId) • ping (no parameters are needed) Metapedia Web Services The Metapedia web services term details by name and by query. • Term search (requires the SessionId and the exact spelling of the term). Additional parameters include: • SessionStatus • Formatting (@plainText - the response is formatted as RTF or plain text) • TermName (requires that the term name be exact) • Search with wild card (requires the SessionId and a phrase with the * or ? wild card). Additional parameters include: • SessionStatus • Formatting (@recordsPerResult, @startIndex, @plainText) • Query (the term name can include a wild card character * or ?) 1.2.2 XSD XML Schema Definition (XSD) outlines the structure of the Metapedia documents provided. The SDK uses two such XSD files: • • 7 ISCommon Services is used to submit authentication information and retrieve a token. Metapedia Services provides the interface to access Metapedia search functions and search results. 2012-12-08 Web service support ISCommon Services The is-common.xsd file provides the complete specification of all available service options for logging in and out, and server ping. The top level summary of these functions include: • • • • • • • • • LoginDetails (UserName, Password, Domain, AuthType, Locale, Additional ) ISWSException (ID, Message, Operation, CallStackTrace, CauseException, CauseID, CauseMessage, CauseDetail) ISSession (SessionId, SessionStatus) Status (Reason, Type or ) LoginResponse (SessionHeader / ISSession) SessionHeader LoginInformation (LoginDetails, LoginToken, SerializedSession) logout (SessionId) ping (PingResponse=timestamp) Metapedia Services The Metapedia_Services.xsd file provides two queries, getTermDetailsByName and search. • • • • • • • • • • • • • • 8 Category CustomAttribute MetapediaTermSummary RelatedTerms Categories Synonyms Keywords CustomAttributes MedapediaTermDetail MetapediaSearchQuery MetapediaTerms MetapediaTermDetail Search (ISM:MetapediaTermDetail) GetTermDetailsByName 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider Using SAP BusinessObjects Information Steward as a web service provider 2.1 Introduction The following web service workflow diagram shows a typical query session. The black represents the IS Common services, while the white represents the Metapedia web services. The following component dependency diagram illustrates how Information Steward web application appears with the Metapedia IS Common Services and the IS Session Management Module leverages existing functionality of other components such as the Apache Rampart security module and the AXIS 2 web services engine. The following message flow diagram illustrates the path that service requests follow. Secure SOAP messages are initiated by clients, the query is processed, and the requested data is securely returned. The Axis 2 module handles the Session Management, serving to validate the session token, sampling the thread every minute, and timing out after 10 minutes. 9 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider The following UML sequence diagram illustrates the interactions between the various components, showing swim lanes for the Common Web Services and the IS Repository that contains the Metapedia data. The client logs on, the Common WS delivers a success message and a logon token to be used for query sessions. Given the stateless operation of the web service, subsequent queries validate the token before allowing the query to proceed. When the query completes, the client can be formally logged out, or the session and token validity can be allowed to expire after 10 minutes. 10 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider The overall system design showing how the Common Web Services and the Metapedia Web Services fit into the BOE system is shown in the following diagram: 11 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider 2.2 Using a WSDL file 12 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider 2.2.1 Common Web Services The Common Web Services provides three functions for session management as follows: • • • ping - checks to see if a webservice is available by returning a timestamp. login - facilitates logging into the Information Steward and retrieval of a session token. logout - ends the session. Note: The path for ISCommon webservices is as follows: http://:/BOE/ISWebServices/Common?wsdl 2.2.1.1 ping The ping Web Service is used to verify that the Information Steward webserver that has the Metapedia SDK is running and responding. A login token is not required, neither is the server domain name parameter required for . The returned result is a date and timestamp. The folowing XML form is used: Parameter Default Required Description ping none Yes The domain name of the server running the BI platform Information Steward. The port number is not required. The server may be pinged with a URL as follows: http:///BOE/InfoStewardApp//ICCExplorer/services/ISCommon/ping Where is a server-specific numerical value, for example 1210021132. A successful response from the server will display a timestamp as follows: 1350189008009 13 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider 2.2.1.2 login The login API is part of the Common Web Service that is used to submit a logon token or username and password credentials to log in to the BI platform system. The system will return a logon token, or SessionId that is to be used when searching for terms and definitions. Because the system is stateless, the login will not be remembered so the token must be used for every search request. The SessionID is a 23-character case-sensitive token (for example: AX88m9bEEBNAqUqztkzmGdU) that is supplied by BI platform security. Three authentication methods are available: • • • A BOE logon token obtained by other means such as by using the JAVA SDK or RESTFul Web Services can be used to avoid having the user enter their name and password. A serialized session is used when a login to BOE has already occurred and/or the access is shared by more than one trusted user. A username and password authenticated login with and a choice of several authentication methods supported by the BI platform. This section discusses how to construct a well-formed SOAP XML request for a login token using the ISCommonBinding interface and how to use the login api. See the is-common.wsdl code listing for details regarding ISCommonBinding services such as login, logout and ping. The following XML code snippet is the blank request form for the ISCommonBinding API for login: ? ? The following XML code snippet is an example of a request form where the LoginInformation section has been filled out: AuthorizedUser PasswordHere is_webserverdoman.name.here.com secEnterprise 14 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider ? ? ? ? The following XML code snippet is an example of a successful response from a request, where the SessionID value of AX88m9bEEBNAqUqztkzmGdU is retrieved: AX88m9bEEBNAqUqztkzmGdU Note: The BI platform passes requests to other layers of the system, including client applications. You can include request header attributes that are not recognized by the BI platform but are recognized by client applications. The following table describes the basic SOAP components of the request message: 15 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider Attribute Description Sample Value XML Dec The XML Declaration is an optional string that lara tion soapenv:En This is a SOAP root element. Within this XML velope tag includes the namespace (XMLNS) of the servers, one for the soap schema, and the other for the SAP Information Steward Web Services. xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://common.isws.sap.com/2012/01/01" soapenv:Head This is a SOAP header tag that, for this ex- additional SOAP hierample, encompasses LoginInformation archy goes here er API for Information Steward. Further information is covered in the next table that follows. soapenv:Body This is a SOAP body tag that, for this exam- ? ard login api. The following table for LoginInformation describes the three methods that may be used to login to Information Steward. An appropriate login token is returned along with a response and status message: 16 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider Table 2-1: LoginInformation Parameter name Description / required values LoginDe tails Parameters: • Username • Password • Domain • Authentication Method • Locale (optional) • Additional Information (optional) LoginDetails sample values • user.john.doe • pasw0rd.hard.to.guess • test.domain.net • secEnterprise • en • Client must already be a BOE registered user and has already logged in to BOE enterprise. This method avoids having to supply a user name and password to the client. ASAB6t1Xe333oZ.UUH54am8 Client must already be a BOE registered user and has already logged in to BOE enterprise. As with LoginTo ken, this method avoids having to supply a user name and password to the client. The main advantage is to share BOE session with several users. ASAB6t1Xe444oZ.UUH54am8 LoginTo ken • Serial izedSes sion • • • Sample Value Response SessionId • The token that was acquired at login must be used in order to log off. SessionStatus • The response will be either: • • SUCCESS FAILED Reason • If SessionStatus is FAILED, the error message will display here. Supported authentication types for the username and password login is as follows: 17 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider Authentication Type Value Description Enterprise secEnterprise BOE BI platform enterprise security LDAP secLDAP Lightweight Directory Access Protocal authentication Windows AD secWinAD Microsoft Windows Active Directory logon SAP secSAPR3 Requires additional parameters such as the SAP client and SAP system. JD Edwards EnterpriseOne secPSE1 Oracle EBC secOraApps PeopleSoft Enterprise secpsenter prise Siebel7 secSeibel7 2.2.1.3 logout The logout Web Service is used to log out of the Information Steward webserver. The login token SessionId (a session CUID supplied from an EnterpriseSession) that was used to login with must be supplied to notify the Information Steward you are leaving. This frees up a license seat for use by another person. The folowing XML form is used: ? 18 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider Table 2-2: logout Parame ter logout Description The sameSession Id logon token obtained from a login request must be used to logout. Response LogoutResponse • Sample Value ASAB6t1Xe333oZ.UUH54am8 The response will be either: • SUCCESS • FAILED Reason • If LogoutResponse is FAILED, the error message will display here. A successful logout response appears as follows: 2.2.2 Metapedia Web Services The Metapedia Web Services provides two functions to allow information retrieval, search and get TermDetailsByName. search Searches for a term that you know the exact spelling of. The following input and output parameters are available as follows: 19 • Input parameters: • Query • recordsPerResult • startIndex • plainText • Output parameters: • Name 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider • • • • Description MetapediaTermURL Author (MetaAuth) LastModifiedDate getTermDetailsByName Searches for matches using an approximate term name plus a wildcard character such as * or ?. The following input and output parameters are available as follows: • Input parameters: • TermName • Output parameters: • Name • Description • MetapediaTermURL • Author • LastModifiedDate • RelatedTerms • Categories • Synonyms • Keywords • CustomAttributes 2.2.2.1 Searching for a Metapedia term To search for a Metapedia term, use the MetapediaServiceBinding interface and use the search forms, search. Optional parameters available are selecting the maximum number of returned entries using the recordsPerResult API, setting the starting page using the startIndex api, and choosing whether or not the returned text is to be plain text or rich text (RTF) formatted, using the plainText api and setting the flag to be "true" (unformatted) or "false" (formatted as RTF, which is the default setting). search The search API is used when you know the exact name of the term and need a definition. The parameters available are as follows: Submitted Data: 20 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider Method Default Required Description SessionId Yes 23-digit token that is obtained from ISCommonBinding > login Reason No recordsPerResult 250 Yes The maximum number of search results to return. 250 is the default value. startIndex 0 Yes If there are multiple pages, the number of the page to display plainText false Yes True is unformatted text, False (the default) returns RTF (Rich Text Format) text Query RelTerm Yes Name of the term to search. Asterisk * and question mark ? symbols are used for wildcard and character substitution searches. *flower will return wildflower and sunflower. Bra?il will return Brazil and Brasil. The XML form that is to be used appears as follows: AUeUnNX1addNgzkHhHOh70Y ? metauth The SessionHeader must include a valid token for that has been acquired using the ISCommonBinding XSD interface. Enter the term to be searched. metauth The response will include the totalTerms found, Name, the Description, the MetapediaTermURL, the Author, and the LastModifiedDate. metauth metaauth http://uspalw201.dhcp.pal.sap.corp:8080/BOE/ InfoStewardApp/1209261045/ICCExplorer/metapediaPage.do ?termName=metauth&name=metauth&rdir=y MetaAuth 2012-09-27 14:30:37 21 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider If a term cannot be found, the only value returned will be totalTerms="0": Any errors that result from the query, such as an expired session token will display a faultcode and faultstring: soapenv:Server Session is expired or session ID is not correct. (COM-101) Note: COM is the error prefix code for Common Web Services. 2.2.2.2 Getting details of a Metapedia term To search for a Metapedia term, use the MetapediaServiceBinding interface and use the search form, getTermDetailsByName and choose whether or not the returned text is to be plain text or rich text (RTF) formatted, using the plainText API and setting the flag to be "true" (unformatted text) or "false" (formatted as RTF, the default setting). getTermDetailsByName This is the API to use when you want to return a search result with several information fields. The parameters available are as follows: 22 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider Method Required Description SessionId Yes 23-digit token that is obtained from ISCommonBind ing > login Reason No plainText TermName Default false Yes true is unformatted text, false returns RTF (Rich Text Format) text Yes Name of the term to search The XML form that is to be used appears as follows: ? ? ? The SessionHeader must include a valid token for that has been acquired using the ISCommonBinding XSD interface. The following example shows the the form that has two items entered, a valid SessionId value, and a TermName: AZJKXqzyymBFvJZwcCem6HE ? flower A successful search results in XML data that appears as follows: flower <P ALIGN="LEFT"><FONT FACE="Tahoma" SIZE="11" COLOR="#000000" LETTERSPACING="0" KERNING="0">green< 23 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider /FONT></P> http://10.162.206.101:8080/BOE/InfoStewardApp/ 1210021132/ICCExplorer/metapediaPage.do?termName=flower &name=flower&rdir=y Administrator 2012-10-05 12:52:56 plant something that grows grow plant Since the default value of plainText which is false was not changed, the text is formatted. Note that the MetapediaTermDetail and MetapediaTermURL is URL-encoded. Characters such as "<" are encoded and appears as < . The & ampersand symbols appears as &. Note: Note that formatting of the preceeding code snippet for MetapediaTermURL has been shortened to fit the page better. Normally the string is does not wrap in this fashion. If the session has expired, the returned XML will appear as follows: soapenv:Server Session is expired or session ID is not correct. (COM-101) 2.3 Security considerations 2.3.1 Configuring the Web Services security policy The Web Services Policy Framework (WS-Policy) has been designed to meet SAP security standards as shipped. Customers can modify the configuration files to apply their own policy. The WS-Policy current meets the following standards: 24 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider • • • • • HTTPS STS (Security Token Service) X509 certificate Symmetric encryption Asymmetric encryption (using private and public keys) Setting up the Web Services security policy involves configuration of the following files: • • • axis2.xml https_policy.xml policy.properties Configuration files are located outside the WAR/JAR file locations. After changing any configuration file settings, restart the application server and Tomcat. 2.3.2 Enabling and disabling the default security policy The security policy is enabled by default, by means of the true setting of the policy.enabled flag found in the policy.properties configuration file. To further secure web services, it is necessary to set up the client and server keystores and generate certificates and import them as described in the following instructions. Disabling the default security policy By disabling the web service security, the web service client can communicate to web services via HTTP as opposed to HTTPS. Turning off security makes it easier to develop and test web services. This setting is a true or false boolean flag setting that enables or disables the security policy found in the policy.properties configuration file using the policy.enabled property. To disable the default security policy: 1. Locate the policy.properties configuration file. \Tomcat6\webapps\BOE\WEB-INF\config\default\policy.properties 2. Change the property policy.enabled value to false. policy.enabled=false 3. Save the modified file. 4. Restart Tomcat. 2.3.3 Configuration options 25 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider 2.3.3.1 Security checklist: Enabling and using SSL Use the following checklist when you are at the stage where you want to activate and test secure services: • • • • The policy.enabled flag has been set to true in the policy.properties configuration file. SSL has been enabled on Tomcat. The java keytool application has been used to create the client and server keystores. The paths pointing to the client and server keystores have been updated from the policy.properties configuration file. • The default location of the default_client.keystore is located at: \InformationSteward\MM\config\default_client.keystore • Access to the HTTPS port has been verified. • Check that the CMC is accessible using HTTPS using the default port 8443: :<8443>/BOE/CMC • Check that the Information Steward is accessible using HTTPS using the default port 8443: :<8443>/BOE/InfoSteward • • The web service you are using has the location of the default_client.keystore and password The secure paths to the WSDL are established, for example: https://uspalw201:8443/BOE/InfoStewardApp/1210151455/ICCExplorer/services/ISCommon?wsdl https://uspalw201:8443/BOE/InfoStewardApp/1210151455/ICCExplorer/services/MetapediaService?wsdl • The request header includes the password request, for example: Set WSS-Password Type: Select the drop down and select “PasswordText” WSS TimeToLive: 2000 2.3.3.2 Using keytool to generate keystores The following instruction illustrates how to use the java application called keytool to generate serv er.keystore and client.keystore with an example password of nosecret, exporting then importing certificate files servercert.cer and clientcert.cer so that both client and server have copies. 26 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider The client.keystore default location for the preceeding server.keystore is in the \InformationSteward\MM\config directory, for example: C:\Program Files (x86)\SAP BusinessObjects\InformationSteward\MM\config\default_client.keystore Configure the security policy for using the serverkey.alias property named server as follows: 1. In the policy.property configuration file, ensure the value of policy.enabled is set to true to turn on security features. 2. Locate the java application keytool.exe. Note that if a java_home environment variable exists, this will point to your preferred Java installation. In a typical SAP Business Objects installation, the java installation may be located at: C:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\win32_x86\jdk\bin\key tool.exe 3. Use the java keystore command to generate keystore for server and client, and export and import client and server certificates as follows: # Generate keystore for server keytool -genkey -alias server -storepass nosecret -validity keytool -genkey -alias client -storepass nosecret -validity and client using password 'nosecret' -keypass nosecret -keyalg RSA -sigalg SHA1withRSA -keystore server.keystore 3650 -keypass nosecret -keyalg RSA -sigalg SHA1withRSA -keystore client.keystore 3650 # Server certificate, export from server.keystore, import to client.keystore keytool -export -alias server -keystore server.keystore -storepass nosecret -file servercert.cer keytool -import -alias server -keystore client.keystore -storepass nosecret -file servercert.cer # Client certificate, export from client.keystore, import to server.keystore keytool -export -alias client -keystore client.keystore -storepass nosecret -file clientcert.cer keytool -import -alias client -keystore server.keystore -storepass nosecret -file clientcert.cer 4. Optionally, you can uncomment the #stskey properties, and generate an sts.keystore and sts.cer certificate. The following code snippet is an example that shows how to create the STS keystore, how to import the server and client certificates (that were created in the previous step), and export the sts.cer certificate, then import that into the client.keystore: # Generate keystore for sts.keystore using password 'nosecret' keytool -genkey -alias stskey -keypass stspass -keyalg RSA -sigalg SHA1withRSA -keystore sts.keystore -storepass nosecret -validity 3650 # Import into sts.keystore the previously generated server and client certificates keytool -import -alias serverkey -keystore sts.keystore -storepass nosecret -file servercert.cer keytool -import -alias clientkey -keystore sts.keystore -storepass nosecret -file clientcert.cer # Export sts certificate and import that into the client.keystore keytool -export -alias stskey -keystore sts.keystore -storepass nosecret -file sts.cer keytool -import -alias stskey -keystore client.keystore -storepass nosecret -file sts.cer Note: The default_client.keystore is located in a default SAP BEO installation at \In formationSteward\MM\config\>. 5. Update the policy document. Note: Sample policy documents can be found at "http://axis.apache.org/axis2/java/rampart/samples.html". For more information regarding policy definitions, see " http://specs.xmlsoap.org/ws/2005/07/securitypolicy/ws-securitypolicy.pdf". 27 2012-12-08 Using SAP BusinessObjects Information Steward as a web service provider 6. Update clientkey.alias and clientkey.password , serverkey.alias and serverkey.password and update the keystore.password. Note that the keystore.type should always be JKS. If applicable, uncomment and update the stskey.alias and stskey.password according to the keys that were generated. 7. If there are any changes to the http or https port number, update ax is2.xml. The following fragment is the relevant section: HTTP/1.1 chunked HTTP/1.1 chunked 8080 8443 8. Restart Tomcat using the SAP BI platform CMC (Central Configuration Manager). 2.3.3.3 Creating a custom security policy Administrators that want to modify the default policy as is delivered in https_policy.xml would create their own policy and save the updated file in the \config\custom directory, and change the path parameter policy.file.path found in the policy.properties file. The default path as shown in this example shows that https_policy.xml is in the same directory as the policy.properties configuration file. . . ## keystore.file.path=default_server.keystore policy.file.path=https_policy.xml 28 2012-12-08 Troubleshooting Troubleshooting 3.1 Web Services log If an error occurs when using the Information Steward Web Services, change the log level to show more details. 1. Log in to the Central Management Console (CMC) as administrator. 2. At the top of the CMC Home screen, select Applications from the navigation list. 3. Select Information Steward Application in the "Applications Name" list. 4. Click Action > Configure Web Services in the top menu tool bar. 5. From the Log Level drop-down list, select one of the following values: Log level Description Debug Log debugging, informational, warning, and error messages. To avoid security risks assoicated with clear text passwords and logins stored in this logfile, use a lower log level setting. Informa tion Log informational, warning, and error messages Warning Log messages that indicate a potential problem Error Log messages that indicate a serious failure 6. Run your Information Steward Web Services client and go view the Web Services log in the Information Steward Explorer log file, which is located in this directory: \SAP BusinessObjects Enterprise XI 4.x\logging 29 2012-12-08 Troubleshooting 30 2012-12-08 Appendix Appendix 4.1 is-common.wsdl The contents of the file is-common.wsdl appears as follows: It is a way of IS web service authentication, which is supported by BOE authentication. It returns a valid session ID when user name, password, domain and authentication type parameters are passed authentication. Otherwise it returns a fault message 31 2012-12-08 Appendix This operation provides IS web service logout in order to release BOE enterprise session object. It returns a status of SUCCESS if logout sessionID parameter is valid. Otherwise it returns a status of FAILED. This operation returns the current timestamp of the server. It returns exception if the webservice is not running. --> 32 2012-12-08 Appendix 4.2 is-common.xsd The contents of the file is-common.xsd appears as follows: 33 2012-12-08 Appendix 4.3 Metapedia_WebServices.wsdl The contents of the file metapedia_webservices.wsdl appears as follows: 34 2012-12-08 Appendix Returns all the Metapedia Terms that match the provided search query. It returns following summary information for each term: Name, Description, Data Steward, Metapedia Term Url and Last Modified By Returns detail information regarding the Metapedia term specified by the name. It returns following information about the term: Categories, Synonyms, Keywords, Related Terms and Custom Attributes in addition to the summary information (Name, Descriotion, Data Steward, Metapedia Term Url and Last Modifed By) 35 2012-12-08 Appendix 4.4 Metapedia_Services.xsd The contents of the file Metapedia_Services.xsd appears as follows: 36 2012-12-08 Appendix The query to search for Metapedia terms. It allows clients to specify a query string and two optional parameters to specify the start index and records per result values Returns all the Metapedia Terms that match the provided search query. It returns following summary information for each term: Name, Description, Data Steward, Metapedia Term URL and Last Modified By Returns detail information regarding the metapedia term specified by the name. It returns following information about the term: Categories, Synonyms, Keywords, Related Terms and Custom Attributes in addition to the summary information (Name, Descrip tion, Data Steward, Metapedia Term URL and Last Modified By) 4.5 Security configuration files 4.5.1 policy.properties The policy.properties is a bootstrap file that is first loaded by Information Steward's Web Service security. For development purposes, this policy can be disabled by setting the policy.enabled flag to false. This file stores the names and passwords for the server and client, the keystore type and password, and optionally, the STS (Security Token Service) name and password. The path to the server keystore can be changed (by default this is \In formation Steward\MM\Config) as well as the path to the https_policy.xml. Modified version of the policy.properties is located at: \Tomcat6\webapps\BOE\WEB-INF\config\custom\policy.properties 37 2012-12-08 Appendix The following table lists the relevant properties, the default value, their purpose and description. Property name Default value Description policy.enabled true A boolean flag to enable or disable the security policy with a setting of true or false. If this flag is set to false, web service security is disabled and the web service client can communicate to web services via HTTP. Turning off security makes it easier to develop and test web services. clientkey.alias Client The name used to refer to the location of the client public keystore. clientkey.pass- nosecret word The password used to access the key pair for the client. serverkey.alias server The name used to refer to the location of the server public keystore. serverkey.pass- nosecret word The password used to access the key pair for the server. keystore.type The keystore type. Use the value JKS, (Java Key Store). JKS is currently the only certified keystore. JKS keystore.pass- nosecret word The password used to open the keystore. stskey.alias n/a The name used to refer to the location of the STS (Security Token Service). By default, this line is commented out. stskey.password n/a The Password used to access the key pair for the STS. By default, this line is commented out. keystore.file.path default_server.keystore The filename, relative or absolute file path to the server’s keystore file. By default, this keystore is located in \InformationSteward\MM\config\>. policy.file.path https_policy.xml The filename, relative or absolute file path to the policy file. Note that after making changes to https_policy.xml configuration, also update the transportReceveiver section in axis2.xml and the connector section in Tomcat's server.xml configuration files. The listing of the policy.properties document and the default values for the current version of Information Steward appears as follows: policy.enabled clientkey.alias clientkey.password serverkey.alias serverkey.password keystore.type keystore.password #stskey.alias #stskey.password =true =client =nosecret =server =nosecret =JKS =nosecret =sts =stspass ## ## keystore and policy file path can be a filename in current directory or absolute file path ## default_client.keystore is located in MM Configuration directory e.g. C:\\Program Files (x86)\SAP BusinessObjects\InformationSteward\MM\config 38 2012-12-08 Appendix ## When changes to the default https policy are made, it is required to update transportReceveiver section in axis2.xml and connector section in Tomcat's server.xml accordingly ## keystore.file.path =default_server.keystore policy.file.path =https_policy.xml 4.5.2 default_server.keystore The default_server.keystore file is a binary that contains several encoded public and private keys security certificates (*.cer), aliases and their access passwords. As such, this file cannot be modied with a text editor. This information is used to encrypt the HTTP channel to HTTPS, which prevents interception of passwords and data. The default_server.keystore is located at: C:\Program Files (x86)\SAP BusinessObjects\InformationSteward\MM\config\ Names and keystore passwords are stored in the axis2.xml configuration file. This information is necessary to open and modify a keystore. In the file policy.properties, the property keystore.file.path contains the path to the de fault_server.keystore binary file. The location of the customized keystore: \Tomcat6\webapps\BOE\WEB-INF\config\custom\default_server.keystore 4.5.3 default_client.keystore The default_client.keystore file is a binary that contains several encoded public and private keys security certificates (*.cer), aliases and their access passwords. As such, this file cannot be modied with a text editor. This information is used to encrypt the HTTP channel to HTTPS, which prevents interception of passwords and data. The default_client.keystore is located at: C:\Program Files (x86)\SAP BusinessObjects\InformationSteward\MM\config\ Names and keystore passwords are stored in the axis2.xml configuration file. This information is necessary to open and modify a keystore. In the file policy.properties, the property keystore.file.path contains the path to the de fault_client.keystore binary file. 39 2012-12-08 Appendix The location of the customized keystore: \Tomcat6\webapps\BOE\WEB-INF\config\custom\default_client.keystore 4.5.4 https_policy.xml The HTTP policy configuration can be changed to suit your business needs. As shipped, HTTPS-based security is enabled to ensure secure delivery of passwords and data between the server and the end user. (should a table for all settings be included here even though this is not "our" file, or can we put a link to a reputable site that will not break) The https_policy.xml file is a standard Apache configuration document that can be found at: \Tomcat6\webapps\BOE\WEB-INF\config\custom\https_policy.xml The default settings of the file are as follows: 4.5.5 axis2.xml Configuration of the HTTP and HTTPS transport sender and receivers can be enabled or disabled, and their associated ports changed. 40 2012-12-08 Appendix The axis2.xml file is a standard Apache configuration document that can be found at: \Tomcat6\webapps\BOE\WEB-INF\config\default The following table lists the relevant property names found within axis2.xml that relates to Information Steward web service configuration. Property name Description transportSender There are two transport senders that are enabled by default. • http • https Comment out the relevant section to disable it. transportReceiver There are two transport receivers that are enabled by default, along with standard listening port numbers. Note that the port numbers must be the same as what is defined in the server configuration within server.xml on Tomcat. • http, port 8080 • https, port 8443 Disable one or the other by commenting out the relevant section. You can also change the port number in the setting. The following code fragment is an excerpt from the axis2.xml file located at: \Tomcat6\webapps\BOE\WEB-INF\config\default HTTP/1.1 chunked HTTP/1.1 chunked 8080 41 2012-12-08 Appendix 8443 Note: For detailed documentation on all Axis2 properties, see "http://axis.apache.org/axis2/java/core/docs/userguide.html". 42 2012-12-08 Index HTTPS access test CMC 26 Iniformation Steward 26 HTTPS port 8443 26 https_policy.xml 28 Message 7 message flow diagram 9 Metapedia SDK 6 Metapedia search features 5 Metapedia_Services.xsd 6, 7, 36 Metapedia_WebServices.wsdl 6 MetapediaSearchQuery 7 MetapediaService?wsdl 6 MetapediaServiceBinding 22 MetapediaServiceBinding, search 20 MetapediaTermDetail 7 MetapediaTerms 7 MetapediaTermSummary 7 I N ID 7 is-common.wsdl 6 is-common.xsd 6, 7 ISCommonBinding 14 ISSession 7 ISWSException 7 Name, search output parameter 19 A authentication information, XSD 7 authentication methods 14 Author, search output parameter 19 AuthType 7 B BOE logon token 14 C CallStackTrace 7 Categories 7 Category 7 CauseException 7 CauseID 7 CauseMessage 7 changing log level Web Services 29 clientkey.alias 37 clientkey.password 37 code snippet login 14 SessionId 14 Common?wsdl 6 component dependency diagram 9 CustomAttribute 7 CustomAttributes 7 D default_client.keystore 39 default_server.keystore 28, 39 Description, search output parameter 19 diagrams component dependency 9 message flow 9 overall system design 9 sequence, Common Web Services & IS Repository 9 web service workflow 9 Domain 7 F faultcode 20 faultstring 20 43 G getTermDetailsByName 7, 19, 22 H J JAVA SDK 14 Java Web Services technologies 6 K keystore.file.path 28, 37 keystore.password 37 keystore.type 37 Keywords 7 L Last modified date, search output parameter 19 Locale 7 LoginDetails 7 LoginInformation 7, 14 LoginResponse 7 LoginToken 7 logout 7, 18 LogoutResponse 18 O Operation 7 overall system design 9 P Password 7 PasswordText 26 ping 7, 13 PingResponse 7 plainText 19, 20 policy.enabled 37 policy.file.path 28, 37 Q Query 19 Query, search 20 R recordsPerResult 19, 20 RelatedTerms 7 request header 26 RESTFul Web Services 14 S M MedapediaTermDetail 7 sapClient 7 sapSystem 7 2012-12-08 Index search 7, 20 Input parameters 19 Output parameters 19 search functions and results, XSD 7 secEnterprise 14 secLDAP 14 secOraApps 14 secpsenterprise 14 secSAPR3 14 secSeibel7 14 secWinAD 14 sequence diagram, UML Common Web Services 9 IS Repository 9 serialized session 14 SerializedSession 7 serverkey.alias 37 serverkey.password 37 SessionHeader 7 SessionId 7, 14, 18 SessionStatus 7 SOAP definition 5 44 SSL enabled 26 startIndex 19, 20 Status 7 stskey.alias 37 stskey.password 37 Synonyms 7 T Timestamp 13 TimeToLive 26 token retrieval, XSD 7 Tomcat, SSL 26 totalTerms 20 W web service workflow diagram 9 Web Services changing log level 29 Web Services Description Language (WSDL) 6 Web Services Interoperability 6 wildcard characters *, ? 5 WSDL definition 5 WSDL, Common Web Services 6 WSDL, Metapedia Web Services 6 X U URL of the Metapedia term, search output parameter 19 UserName 7 username and password authenticated login 14 XML definition 5 XML Schema Definition (XSD) 7 XSD definition 5 XSD, ISCommon Services 7 XSD, Metapedia Services 7 2012-12-08