TIBCO® API Exchange Gateway User Guide Version 2.4.1 July 2021 Copyright © 2004-2021. TIBCO Software Inc. All Rights Reserved. 2 | Contents Contents Contents 2 Introduction to TIBCO API Exchange Gateway 19 Design-time Components 20 Config UI 21 Studio 21 Runtime Components 21 Gateway Operational Layer 21 Gateway Management Layer 22 Deployment Architecture 24 Single Server Deployment Architecture 25 Distributed Deployment Architecture 28 Getting Started 32 Examples Overview 32 Examples 33 Configure an Endpoint Operation for TIBCO API Exchange Gateway 34 Creating a New Configuration 35 Configuring Partner Group 35 Configuring Partner Data 36 Configuring a Facade Operation 36 Configuring a Target Operation 37 Configuring an Authorization Configuration 38 Configuring Routing Configuration 39 Saving the Gateway Configuration 40 Testing the Gateway configuration 40 Working with Studio 41 Starting Studio 41 Loading the Default ASG_DefaultImplementation Project 42 TIBCO® API Exchange Gateway User Guide 3 | Contents Editing Validating and Building the Default ASG_DefaultImplementation Project 43 Validation Tool (asg-validate) 50 Running asg-validate Using asg-tools 51 Log File for asg-validate 51 Limitations of asg-validate 52 Runtime Properties 52 Runtime Properties of Core Engine 52 Runtime Properties of Central Logger 97 Building an EAR File at the Command Line 107 Core Engine Configuration 109 Core Engine 109 Starting Core Engine 109 Processing Units of Core Engine 111 Configure Log Files Settings 113 Logging Levels of Core Engine 116 Apache Module for TIBCO API Exchange Gateway 118 Installing Apache HTTP Server 119 Installing Apache HTTP Server with SSL 119 Configuring Apache HTTP Server Using HTTP Transport 119 On the Windows Platform 120 Configuration On the UNIX Platform 121 Running the Apache HTTP Server 121 On the Windows Platform 121 Running On the UNIX Platform 122 Secure Communications 122 Mutual SSL Authentication 122 SSL Communications Configuration 127 Configure the Apache Server for Basic HTTP Authentication 137 Configure Apache Module for RVRD Setup through a Firewall (DMZ) 144 Configure Apache HTTP Server as Reverse Proxy 147 TIBCO® API Exchange Gateway User Guide 4 | Contents Transport Communication 151 Facade Operation Requests 151 Central Logger 152 Global Throttle Manager 152 Rendezvous Transport Communication 153 Enabling Rendezvous Communication for TIBCO API Exchange Gateway 153 Configuration Setup 158 Setting Rendezvous Transport Properties 159 Secure Deployments with TIBCO Rendezvous 167 Configuration for Secure Rendezvous Daemon 168 Enabling Facade HTTP Transport 179 Enable Facade HTTPS Transport 180 Setting SSL Properties 180 Download Tomcat Native Library 181 Setting Content-Type for Error Response 184 Endpoint Ports 185 JMS Transport Communication 189 SOAP JMS Transport 189 SSL Support for JMS Transport 200 Set JMS Message Delivery and Acknowledgment Mode 201 JMS Message Delivery Modes 201 JMS Message Acknowledgment Mode 203 Non-Standard JMS Headers 206 Setting up JMS Properties 206 ESB Channel 208 Enabling ESB Channels 209 Edit asg.properties File for ESB Channel Properties 210 Create queues on EMS Server 214 Create Users On EMS Server 215 Config UI 216 TIBCO® API Exchange Gateway User Guide 5 | Contents Starting GUI 217 Accessing Config UI through HTTPS Transport 218 Changing Login Host and Port Information 222 Authentication Process for Config UI 223 Authentication Properties 224 Configuration Setup for Authentication Process 226 LDAP Server Authentication 226 File-Based Authentication 228 Default Authentication 232 Enable Debug Logging for Config UI 233 Creating Properties File 233 Using Properties File in the TRA File 235 Configuring Directory for Log Files 235 Manage a Gateway Project Configuration 236 Publish Project Configuration 237 Publishing Configuration 237 Change Log Level Settings 238 Updating Project Configuration 240 Validate Configuration 241 Project Configuration 241 MAPPING 242 SECURITY 245 MONITORING 249 ROUTING 253 PARTNER 269 Set Runtime Properties 273 Setting General Properties 274 Setting Monitoring Properties 275 Setting Database Properties 280 Setting Transport Properties 281 Security Properties 297 TIBCO® API Exchange Gateway User Guide 6 | Contents Transaction Pipeline processing 306 Request Pipeline Processing 306 Response Pipeline Processing 309 Parsing Step 310 Set the Partner Identity for Request 311 Set the Routing Key for Request 312 Enrich the Audit Trail Log for Request 312 Logging Request Headers 313 Validate the Request Content 315 Set Metric Increment for Content-Based Throttles 316 Set Sticky Key for Load-Balancing with StickyResourceAffinity 317 Overriding HTTP Headers 317 Parsing XSLT Documents 320 Parsing Output Document Schema 325 Mappings and Transformations 330 Mapping Types 332 Mapping Configuration 332 Transformations (XSLT Mapping) 335 Set error codes for content validation 337 Validation 337 Implementing Request Validation 337 Map the Protocol Headers in Request Context 339 Enumeration Orchestration 340 Response Transformation 341 Mapping Schemas 342 Mapping Container 342 Mapping XSLT Schema 344 Context Document 344 JSON XML Transformation 350 Converting XML Message to JSON Message 352 Converting JSON Message to XML Message 356 TIBCO® API Exchange Gateway User Guide 7 | Contents XSLT Functions for URL Encode and URL Decode 359 Decode() Function 359 Encode() Function 361 XSLT Functions for Base64 Encode and Decode 364 textToBase64() 364 base64ToText() 364 Custom Java Functions 364 Java Function 365 XSLT File 365 Pass-Through Gateway 365 Starting Config UI 366 Enabling Default Operation 366 Configuring DefaultOperation Facade Operation 367 Configuring Target Operation for DefaultOperation 368 Configuring Routing Key for DefaultOperation 369 Configuring Facade Access for DefaultOperation 370 Pass-Through Special Characters in Query String 371 Proxy Server 371 Configuring HTTP Headers 372 Routing Overview 374 Routing Key 375 Routing Key using XSLT 376 How to Derive and Configure Routing Key 376 Routing Use Case using XSLT 382 Configuration 382 Preferred Routing 385 Use Case for Preferred Routing 386 Overriding Preferred Routing Key using XSLT 387 Target Operation Group 389 Overview 389 Routing Algorithms for Target Operation Group 391 TIBCO® API Exchange Gateway User Guide 8 | Contents LoadBalanced 391 RoundRobin 391 Weighted RoundRobin 393 RoundRobin with Failover 395 Weighted RoundRobin with Failover 402 Sticky Resource Affinity 402 Target Operation Group Configuration 404 Configuring a Target Operation Group 404 Configuring a RoundRobin Target Operation Group 406 Configuring a WeightedRoundRobin Target Operation Group 407 Configuring a RoundRobinWithFailOver Target Operation Group 408 Configuring a WeightedRoundRobinWithFailOver Target Operation Group 410 StickyResourceAffinity Target Operation Group Configuration 411 HealthCheck for Reference 417 HealthCheck Modes for a Target Operation 417 HealthCheck Methods for Timer Mode 418 HealthCheck Configuration for Target Operation 420 Configuration for Reset Mode of HealthCheck 420 Configuration for Timer Based HealthCheck 421 Throttles Overview 426 Facade Throttles 426 Service Throttles 427 Throttle Types 427 Rate 428 Quota 429 High Water Mark 430 Error 430 Monitor Time Modifiers 432 Configuring Time Modifier Throttles 433 Throttle Chaining 434 Throttle Counter 435 TIBCO® API Exchange Gateway User Guide 9 | Contents Throttle UpdateInterval 435 Configuring Throttles 436 Configuration Parameters for Throttles 436 Creating a Throttle Policy Definition 437 Content Based Throttles 440 Configure Content-Based Throttles 441 Configuring Throttle 441 Define XSLT File 442 Uploading XSLT File 446 Payload Size Throttles 446 Payload Size Throttle Types 447 Configuring Payload Size Throttles 449 Traffic Shaping 451 Configuration 451 Shared Throttles Overview 452 Configuration Setup for Shared Throttles 452 Example Use Case 456 Authentication and Authorization 458 User Authentication 458 Transport and Protocol Level Authentication 458 WS Security Services Authentication 459 Security Service Providers 461 Web Services Security (WSS) Properties 461 Types of Security Service Providers 461 Configuring LDAP Authentication Service Provider (LDAP ASP) 462 Configuring Trust Identity Provider 473 Properties for Subject Identify Provider (SIP)Configuring Subject Identity Provider 475 Configuring WSS Service Provider 478 Limitations 479 Web Services Security Authentication 480 Registering WSS resources with TIBCO API Exchange Gateway 482 TIBCO® API Exchange Gateway User Guide 10 | Contents Defining the WSS security operations 483 Configure Secure Services with TIBCO API Exchange Gateway 484 Altering List of Algorithms (Optional) 485 Define DSS Properties for Services 485 Configuring Services 492 Partner Authorization Overview 493 Operation Identification 494 Partner Identification 494 Partner Authorization 498 Overview of Security Policies 499 Security Concepts 499 Types of Security Policies 503 Authentication 504 Authorization 506 Confidentiality 506 Integrity 507 CredentialMapping 507 Manage Policies 508 Configure Shared Resource 508 Create Policy 510 Registering Policy 514 Applying Policies 515 Policy Use Cases 517 Authentication Policies 517 Creating a User Account in the Microsoft Active Directory for TIBCO API Exchange Gateway 527 Mapping the Service Principal Name (SPN) to a Microsoft User Account 528 Generating a Keytab File for an SPN 529 TIBCO® API Exchange Gateway User Guide 11 | Contents Sample Custom LoginModule