Axway API Gateway Policy Developer Guide

Axway API Gateway Policy Developer Guide
 API Gateway
Version 7.5.2
31 March 2017
Policy Developer Guide
Copyright © 2017 Axway
All rights reserved.
This documentation describes the following Axway software:
Axway API Gateway 7.5.2
No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of the copyright owner, Axway.
This document, provided for informational purposes only, may be subject to significant modification. The descriptions and information in this document may not necessarily accurately represent or reflect the current or planned functions of this product. Axway may change this publication, the product described herein, or both. These changes will be incorporated in new versions of this document. Axway does not warrant that this document is error free.
Axway recognizes the rights of the holders of all trademarks used in its publications.
The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and access to these sites are provided for your convenience only. Axway does not control, endorse or guarantee content found in such sites. Axway is not responsible for any content, associated links, resources or services associated with a third-party site.
Axway shall not be liable for any loss or damage of any sort associated with your use of third-party content.
Contents
Preface
37
Who should read this guide
37
How to use this guide
37
Related documentation
38
Axway user forums
38
Support services
38
Training services
38
Accessibility
39
Screen reader support
39
Support for high contrast and accessible use of colors
39
1 Get started
Policy development with Policy Studio
40
40
Overview
40
Policy Studio projects
40
API Gateway instances and groups
41
Filters
41
Policies
41
Message attributes
42
Selectors
43
Faults and errors
44
Policy shortcuts
44
Alerts
45
Policy containers
45
Policy contexts
45
Listeners
45
Remote hosts
46
Servlet applications
46
Service virtualization
46
Start the API Gateway tools
47
Overview
47
Before you begin
47
Launch API Gateway Manager
47
Start Policy Studio
48
Create a Policy Studio project
48
Overview
48
Launch the New P roject wizard
49
Enter project details
49
Axway API Gateway 7.5.2
Policy Developer Guide 3
Select a project starting point
49
Create API Manager projects
52
Upgrade of configuration from previous versions
52
Configure the sample policies
52
Overview
52
Enable the sample services interface
53
Configure a different sample services interface
54
StockQuote demo service
54
Remote host settings
55
Conversion sample policy
56
Overview
56
REST to SOAP policy
56
Run the conversion sample
57
Security sample policies
58
Overview
58
Signature verification
58
Run the signature verification sample
59
Encryption and decryption
59
Run the encryption and decryption sample
61
Throttling sample policy
62
Overview
62
Throttling policy
62
Run the throttling sample
62
Virtualized service sample policy
63
Overview
63
Virtualized service policies
64
Run the virtualized service sample
67
Stress test with send request (sr)
67
Overview
67
Basic sr command examples
68
Advanced sr command examples
68
sr command arguments
69
Further information
71
Send a request with API Tester
72
Overview
72
Create a request in API Tester
72
Further information
73
2 Manage policies
Configure policies manually
74
74
Overview
74
Configuration
74
Configure global policies
Overview
Axway API Gateway 7.5.2
76
76
Policy Developer Guide 4
Global policy roles
77
Select a global policy
78
Configure global policies in a policy shortcut chain
79
Configure global policies for a service
80
Show global policies
81
Configure policy assemblies
81
Overview
81
Configure a policy assembly
82
Apply a policy assembly
83
3 Web services
Register and secure web services
84
84
Overview
84
WSDL and XML schema cache
85
JSON schema cache
85
WSDLs from a UDDI registry
85
Data maps
85
Policy Studio filters
85
Configure policies from WSDL files
86
Overview
86
API Gateway as the web service initiator
86
API Gateway as the web service recipient
87
Import WSDL summary
88
Import a WSDL file
88
Configure a security policy
90
Configure recipient security settings
91
Configure initiator security settings
91
Configure recipient policy filters
92
Configure initiator policy filters
94
Edit the recipient or initiator WS-Policy
96
Configure a recipient WCF WS-Policy
97
Remove security tokens
99
Manage web services
101
Overview
101
Manage web services and groups
101
Register a web service
101
Results of registering a web service
102
Export a web service
103
Update a web service
104
Change the operations exposed by a web service
105
Delete a web service
106
Use scripts to manage web services
106
Publish the WSDL
106
Manage WSDL and XML schema documents
Axway API Gateway 7.5.2
107
Policy Developer Guide 5
Overview
107
Structure of the global cache
108
View cached WSDL or XML schema documents
109
Add XML schemas to the cache
110
Add WSDL documents to the cache
111
Update cached WSDL or XML schema documents
111
Delete cached WSDL or XML schema documents
112
XML schema and WSDL document validation
113
XML schema and WSDL document limitations
113
Version and duplicate management
115
Validate messages against XML schemas
115
Test a WSDL for WS-I compliance
115
Manage JSON schemas
116
Add JSON schema
116
Add JSON schema container
117
Manage data maps
117
Add data map
117
Data map options
119
Use a data map in a policy
120
Use external parameters in a data map
123
123
Expose a web service as a REST API
123
Overview
123
Summary of steps
123
Virtualize a SOAP web service
124
Define a REST API
125
Route REST requests through the virtualized SOAP service
126
Test the REST to SOAP mapping
130
Develop REST APIs in Policy Studio
131
Overview
131
Virtualized REST APIs
132
Virtualize a REST API
132
Virtualize a REST API method
134
Example inbound parameters
136
Monitor APIs in API Gateway Manager
138
Connect to a UDDI registry
139
Overview
139
Configure a registry connection
140
Secure a connection to a UDDI registry
141
Retrieve WSDL files from a UDDI registry
143
Overview
143
UDDI concepts
143
UDDI definitions
144
Configure a registry connection
146
Axway API Gateway 7.5.2
Policy Developer Guide 6
WSDL search
146
Quick search
147
Name search
148
Advanced search
149
Advanced options
150
Publish
153
Publish WSDL files to a UDDI registry
154
Overview
154
Find WSDL files
155
Publish WSDL files
155
4 Messaging
Configure messaging services
161
161
Overview
161
Prerequisites
162
Configure API Gateway messaging using the JMS wizard
162
Configure global JMS services in external connections
163
Configure embedded Apache ActiveMQ in API Gateway settings
163
Monitor messaging using API Gateway Manager
163
Configure a JMS service
163
Overview
163
General configuration
164
Apache ActiveMQ and Standard JMS settings
164
IBM WebSphere MQ settings
165
Settings for all service types
165
Configure advanced settings
166
Next steps
167
Configure a JMS session
167
JMS session configuration
167
Monitoring options
168
Next steps
169
Configure a JMS consumer
169
Overview
169
JMS Message source
169
JMS consumer type
170
Message processing
170
Logging settings
171
Send to JMS
172
Overview
172
Request settings
172
Response settings
175
Read from JMS
176
Overview
176
Message source
177
Axway API Gateway 7.5.2
Policy Developer Guide 7
JMS consumer type
177
Message processing
178
5 General configuration
Manage Policy Studio projects
179
179
Overview
179
Create a new project
179
Open an existing project
179
Save changes to a project
180
Deploy changes to a project
180
Add an API to a project
180
Virtualize a web service
180
Change the project passphrase
180
Export configuration packages
181
Import configuration into a project
181
Manage multiple projects
181
Close a project
182
Manage API Gateway connections
182
Overview
182
Create a new project based on an API Gateway instance
182
Open an existing project
182
Open a connection when deploying
183
Unlock a server connection
183
Global configuration
184
Overview
184
API Gateway settings
184
Web service repository
185
API Gateway instances
185
Policies
186
Certificates and keys
186
API Gateway user store
186
System alerts
187
External connections
187
Caches
188
Black list and White list
188
WSDL and XML schema document bundles
189
Scripts
189
Stylesheets
189
References
190
Policy Studio preferences
190
Overview
190
Environmentalization
190
FIPS mode
191
Map graphical editor
191
Axway API Gateway 7.5.2
Policy Developer Guide 8
Policy colors
191
Proxy settings
192
Runtime dependencies
192
SSL settings
193
Status bar
193
Trace level
194
WS-I settings
194
XML settings
195
Policy Studio viewing options
196
Overview
196
Filter the tree
196
Configure viewing options
196
Configure the policy filter palette
196
Import API Gateway configuration fragment
197
Overview
197
Import configuration fragment
197
View differences
198
What is imported
198
Upgrade configuration from an earlier version
199
Export API Gateway configuration
200
Overview
200
What is exported
200
Export configuration items
201
Compliance validation tools
202
Overview
202
Validate FIPS compliance
202
Validate Suite B compliance
202
Validate Suite B Top Secret compliance
203
Upgrade log analysis
203
Manual upgrade log analysis
203
Automatic upgrade log analysis
204
Example upgrade log analysis
205
Example critical/major issues and recommended solutions
206
Example warnings and recommended solutions
208
Oracle Security Service Module settings (10g)
211
Overview
211
Prerequisites
211
Settings
213
Name authority definition settings
214
Kerberos configuration
214
Kerberos configuration file — krb5.conf
215
Advanced settings
215
Native GSS library
216
Axway API Gateway 7.5.2
Policy Developer Guide 9
6 Manage deployments
Manage API Gateway deployments
217
217
Overview
217
Create a project in Policy Studio
217
Edit a project configuration in Policy Studio
218
Deploy to a server in Policy Studio
218
Manage deployments in API Gateway Manager
218
Compare and merge configurations in Policy Studio
218
Manage administrator users in API Gateway Manager
219
Configure policies in Policy Studio
219
Deploy API Gateway configuration
219
Overview
219
Deploy configuration in Policy Studio
220
View deployment results in Policy Studio
220
API Gateway configuration packages
221
Create a configuration package in Policy Studio
222
Deploy packages in Policy Studio
222
Deploy packages in API Gateway Manager
222
Deploy packages on the command line
223
Compare and merge API Gateway configurations
223
Overview
223
Compare and merge configurations
223
Comparison results
224
Filter differences
225
Select differences for merging
225
Manage admin users
226
Overview
226
Admin user privileges
226
Admin user roles
227
Add a new admin user
228
Remove an admin user
228
Reset an admin user password
228
Manage admin user roles
228
Configure a password policy for admin users
229
7 Environment configuration
Manage X.509 certificates and keys
230
230
Overview
230
View certificates and keys
230
Configure an X.509 certificate
231
Configure a private key
233
Configure HSMs and certificate realms
235
Configure SSH key pairs
239
Configure PGP key pairs
241
Axway API Gateway 7.5.2
Policy Developer Guide 10
Global import and export options
242
Further information
243
Manage API Gateway users
243
Overview
243
API Gateway users
243
Add API Gateway users
243
API Gateway user attributes
244
API Gateway user groups
244
Add API Gateway user groups
244
Update API Gateway users or groups
245
Configure system alerts
245
Overview
245
Configure an alert destination
245
Configure an alert filter
252
Policy execution scheduling
256
Overview
256
Cron expressions
256
Add a schedule
259
Add a policy execution scheduler
259
Global caches
259
Overview
259
Local caches
260
Distributed caches
261
Distributed cache settings
263
Distributed caching example
264
Example of caching response messages
265
Cross-Origin Resource Sharing
268
Overview
268
Add a CORS profile
269
Configure CORS for HTTP services
271
Configure CORS for relative paths
272
Key Property Store
273
Overview
273
KPS tables and collections
273
Enter data in a KPS table
274
KPS data sources
274
Add a KPS collection
275
Edit a KPS collection
275
Add a KPS table
277
Define the KPS table structure
277
Further information
278
8 API Gateway instances
Configure API Gateway instances
Axway API Gateway 7.5.2
279
279
Policy Developer Guide 11
Overview
279
Add remote hosts
280
Add HTTP services
280
Add SMTP services
280
Add file transfer services
280
Add policy execution scheduling
281
Configure JMS messaging system
281
Add Amazon SQS queue listener
281
Add FTP poller
281
Add directory scanner
281
Add POP client
282
Configure TIBCO
282
API Gateway settings
282
Cryptographic acceleration
282
Configure remote host settings
283
Overview
283
General settings
283
Address and load balancing settings
284
Advanced settings
285
Configure watchdogs
287
Configure an incoming remote host
288
Configure HTTP watchdog
288
Overview
288
Configuration
289
Configure HTTP services
290
Overview
290
HTTP services groups
290
HTTP and HTTPS interfaces
292
HTTPS interfaces only
296
Management services
299
Packet sniffers
301
Overview
301
Configuration
302
Configure conditions for HTTP interfaces
303
Overview
303
Configure Requires Endpoint condition
304
Configure Requires Link condition
305
Configure a transparent proxy
305
Overview
305
Configure transparent proxy mode for incoming interfaces
305
Configure transparent proxy mode for outgoing calls
306
Transparent proxy example
306
Configure relative paths
Overview
Axway API Gateway 7.5.2
308
308
Policy Developer Guide 12
Configure a relative path
308
Nested relative paths
312
Static content providers
315
Static file providers
316
Servlet applications
317
Web service resolvers
318
Check URI path syntax in incoming HTTP requests
320
Configure WebSocket connections
320
WebSocket protocol overview
320
Configure a WebSocket connection
321
Monitor a WebSocket connection
324
WebSocket connection example
324
Configure virtual hosts
328
Overview
328
Configure virtual hosts for HTTP services
329
Configure virtual hosts for REST APIs
330
Configure SMTP services
331
Overview
331
Add an SMTP service
332
Add an SMTP interface
333
Configure policy handlers for SMTP commands
334
SMTP authentication
340
SMTP Content-Transfer-Encoding
341
Deployment example
342
Configure a file transfer service
347
Overview
347
General settings
347
File upload settings
348
Secure services settings
350
Command settings
350
Access control settings
351
Message settings
352
Directory settings
352
Logging settings
353
Traffic monitor settings
354
Configure an FTP poller
354
Overview
354
General settings
354
Scan settings
355
Connection type settings
356
Configure a directory scanner
358
Overview
358
Input settings
358
Processing settings
359
Axway API Gateway 7.5.2
Policy Developer Guide 13
On completion settings
360
Traffic monitor settings
360
Configure a POP client
361
Overview
361
Configuration
361
TIBCO integration
362
Overview
362
TIBCO Rendezvous integration
362
TIBCO Rendezvous listener
362
Overview
362
Configuration
363
Configure Amazon SQS queue listener
363
Overview
363
General settings
364
Configure AWS client settings
365
Further information
367
Cryptographic acceleration
367
Overview
367
General configuration
368
Conversations for crypto engines
369
Cryptographic acceleration conversation: request-response
Conversations for crypto engines
9 External connections
External connections
369
369
371
371
Authentication repository profiles
372
Connection sets
372
Client credentials
373
Database connections
373
ICAP servers
374
Sentinel servers
374
JMS services
374
Kerberos connections
374
LDAP connections
375
Proxy servers
375
RADIUS clients
375
SiteMinder and SOA Security Manager
375
SMTP servers
376
Syslog servers
376
TIBCO
376
Tivoli
376
URL connection sets
377
XKMS connections
377
Configure authentication repositories
Axway API Gateway 7.5.2
377
Policy Developer Guide 14
Axway PassPort repositories
378
CA SiteMinder repositories
378
Database repositories
379
Entrust GetAccess repositories
381
Local repositories
382
LDAP repositories
382
Oracle Access Manager repositories
386
Oracle Entitlements Server 10g repositories
388
RADIUS repositories
388
RSA Access Manager repositories
389
Sun Access Manager repositories
390
Tivoli repositories
390
Configure Axway PassPort authentication repositories
391
Overview
391
Configuration
391
Axway PassPort repository registration
392
Configure client credentials
395
Overview
395
Configure API key client credential profiles
395
Configure HTTP basic/digest client credential profiles
397
Configure Kerberos client credential profiles
397
Configure database connections
399
Overview
399
Prerequisites
399
Configure the database connection
400
Database connection pool settings
401
Connection validation
402
Test the connection
402
Configure database queries
402
Overview
402
Configuration
402
Configure ICAP servers
404
Overview
404
Server settings
404
Security settings
404
Advanced settings
405
Further information
405
Configure Sentinel servers
406
Sentinel server overview
406
General settings
406
Further information
407
Configure Kerberos clients
407
Overview
407
Kerberos endpoint settings
407
Axway API Gateway 7.5.2
Policy Developer Guide 15
Kerberos Constrained Delegation settings
410
Advanced settings
411
Configure Kerberos principals
412
Overview
412
Configuration
413
Configure Kerberos services
414
Overview
414
Kerberos endpoint settings
415
Advanced settings
416
Kerberos keytab concepts
417
Configuration
Configure LDAP directories
417
418
Overview
418
General configuration
418
Authentication configuration
419
Test the LDAP connection
420
Additional JNDI properties
421
Configure proxy servers
421
Overview
421
Configuration
422
Configure RADIUS clients
422
Overview
422
Configuration
422
Configure SiteMinder/SOA Security Manager connections
423
Prerequisites
423
Add a new connection
425
SiteMinder and SOA Security Manager connection settings
425
SOA Security Manager connection settings
426
Configure SMTP servers
426
Overview
426
Configuration
426
Configure trusted certificates for SMTP connections
427
Configure TIBCO Rendezvous daemons
427
Overview
427
Configuration
428
Configure Tivoli connections
429
Prerequisites
429
Configuration
429
Configure XKMS connections
430
Overview
430
Configuration
431
10 Amazon Web Services filters
Send to Amazon SQS
Axway API Gateway 7.5.2
432
432
Policy Developer Guide 16
Overview
432
General settings
432
Send message settings
433
Advanced settings
433
Further information
434
Upload to Amazon S3
434
Overview
434
General settings
434
Further information
435
11 Attribute filters
Compare attribute
436
436
Overview
436
Configuration
437
Extract REST request attributes
438
Overview
438
Configuration
439
Extract WSS header
440
Overview
440
Configuration
440
Extract WSS timestamp
441
Overview
441
Configuration
441
Extract WSS UsernameToken element
441
Overview
441
Configuration
442
Get cookie
442
Overview
442
Configuration
442
Attribute storage
442
Insert SAML attribute assertion
443
Overview
443
Assertion details settings
445
Assertion location settings
445
Subject confirmation method settings
446
Advanced settings
449
Retrieve attributes from JSON message
451
Overview
451
Configuration
451
JSON Path examples
452
Exceptions
454
Retrieve attribute from directory server
454
Overview
454
Database settings
454
Axway API Gateway 7.5.2
Policy Developer Guide 17
Advanced settings
Retrieve attribute from HTTP header
456
458
Overview
458
Configuration
458
Retrieve attribute from SAML attribute assertion
459
Overview
459
Details settings
460
Trusted issuer settings
461
Subject settings
461
Lookup attributes settings
461
Retrieve attribute from SAML PDP
462
Overview
462
Request settings
462
Response settings
465
Retrieve attribute from Tivoli
Configuration
Retrieve attribute from message
465
465
466
Overview
466
Configuration
466
Retrieve attribute from database
467
Overview
467
Database settings
467
Advanced settings
468
Retrieve attribute from user store
470
Overview
470
Database settings
470
Advanced settings
470
12 Authentication filters
Attribute authentication
472
472
Overview
472
Configuration
473
API key authentication
474
Overview
474
General settings
474
API key settings
475
Advanced settings
476
Check session
478
Overview
478
Configuration
478
Create session
478
Overview
478
Configuration
479
End session
Axway API Gateway 7.5.2
480
Policy Developer Guide 18
Overview
480
Configuration
480
CA SOA Security Manager authentication
481
Overview
481
Prerequisites
481
Configuration
482
XmlToolkit.properties file
483
HTML form-based authentication
484
Overview
484
General settings
485
Session settings
486
Invalid login attempts settings
486
HTTP basic authentication
487
Overview
487
General settings
487
HTTP digest authentication
489
Overview
489
General settings
490
HTTP header authentication
491
Overview
491
Configuration
491
IP address authentication
492
Overview
492
Configuration
492
Configure subnet masks
493
Insert SAML authentication assertion
495
Overview
495
Assertion details settings
496
Assertion location settings
497
Subject confirmation method settings
497
Advanced settings
501
Insert timestamp
502
Overview
502
Configuration
503
Insert WS-Security UsernameToken
503
Overview
503
General settings
504
Kerberos client authentication
505
Overview
505
Kerberos client settings
505
Kerberos token profile settings
507
Kerberos service authentication
507
Overview
507
General settings
508
Axway API Gateway 7.5.2
Policy Developer Guide 19
Kerberos standard settings
508
Message level settings
509
Transport level settings
509
Advanced SPNEGO settings
509
SAML authentication
510
Overview
510
Details settings
511
Trusted issuer settings
512
SAML PDP authentication
512
Overview
512
Request settings
513
Response settings
516
SSL authentication
Overview
STS client authentication
516
516
516
Overview
516
Example request
517
Request settings
518
Policies settings
523
Routing settings
523
Response settings
524
Advanced settings
524
WS-Security UsernameToken authentication
526
Overview
526
General settings
527
13 Authorization filters
RSA Access Manager authorization
530
530
Prerequisites
530
General settings
531
Attribute authorization
532
Overview
532
Configuration
532
Axway PassPort authorization
534
Overview
534
Configuration
534
CA SOA Security Manager authorization
535
Overview
535
Prerequisites
535
Configuration
536
Certificate attribute authorization
536
Overview
536
Configuration
537
Entrust GetAccess authorization
Axway API Gateway 7.5.2
538
Policy Developer Guide 20
Overview
538
GetAccess WS-Trust STS settings
538
GetAccess SAML PDP settings
539
Insert SAML authorization assertion
539
Overview
539
Assertion details settings
540
Assertion location settings
541
Subject confirmation method settings
542
Advanced settings
545
LDAP attribute authorization
547
Overview
547
General settings
547
Advanced settings
549
SAML authorization
549
Overview
549
Details settings
550
Trusted issuer settings
551
Optional settings
551
SAML PDP authorization
551
Overview
551
Request settings
552
Response settings
555
Tivoli authorization
555
Prerequisites
555
Configuration
556
XACML PEP authorization
557
Overview
557
Example XACML request
558
XACML settings
558
Routing settings
562
Advanced settings
562
14 CA SiteMinder filters
564
Prerequisites
564
CA SiteMinder certificate authentication
564
Configuration
CA SiteMinder session validation
565
566
Configuration
566
CA SiteMinder logout
567
CA SiteMinder authorization
567
Configuration
15 Certificate filters
Introduction to certificate validation
Axway API Gateway 7.5.2
568
569
569
Policy Developer Guide 21
Overview
569
Certificate validation filters
570
Dynamic CRL certificate validation
570
Overview
570
Example CRL-based validation policy
570
Configuration
571
CRL LDAP validation
571
Overview
571
Configuration
572
Static CRL certificate validation
572
Overview
572
Example CRL-based validation policy
573
Configuration
574
CRL responder
574
Overview
574
Configuration
574
Certificate chain check
575
Overview
575
Configuration
575
Certificate validity
576
Overview
576
Configuration
576
Create thumbprint from certificate
576
Overview
576
Configuration
576
Extract certificate attributes
577
Overview
577
Generated message attributes
577
Configuration
580
Find certificate
581
Overview
581
Configuration
581
OCSP client
582
Overview
582
General settings
583
Message settings
583
Routing settings
584
Advanced settings
584
Integration with Axway Validation Authority
585
Validate certificate store
585
Overview
585
Configuration
586
Deployment example
586
XKMS certificate validation
588
Axway API Gateway 7.5.2
Policy Developer Guide 22
Overview
588
Configuration
588
16 Cache filters
589
Cache attribute
589
Overview
589
Configuration
589
Create key
590
Overview
590
Configuration
590
Check if attribute is cached
591
Overview
591
Configuration
591
Remove cached attribute
592
Overview
592
Configuration
592
17 Content filtering filters
593
Scan with ClamAV anti-virus
593
Overview
593
Configuration
593
Content type filtering
594
Overview
594
Allow or deny content types
594
Configure MIME types
595
Content validation
595
Overview
595
Manual XPath configuration
595
XPath wizard
596
Send to ICAP
596
Overview
596
Configuration
596
Example policies
596
JSON schema validation
597
Overview
597
Configuration
598
Generate a JSON schema using Jython
599
Exceptions
600
Scan with McAfee anti-virus
600
Overview
600
Prerequisites
601
Configuration
601
Message status
603
Load McAfee updates
603
Axway API Gateway 7.5.2
Policy Developer Guide 23
Message size filtering
604
Overview
604
Configuration
604
Schema validation
605
Overview
605
Select the schema
605
Select which part of the message to match
606
Advanced settings
606
Report schema validation errors
609
Scan with Sophos anti-virus
610
Overview
610
Prerequisites
611
Sophos configuration settings
611
Threatening content
612
Overview
612
Scanning settings
612
MIME type settings
613
Regular expression format
613
Throttling
614
Overview
614
Rate limit settings
614
Advanced settings
615
Use multiple throttling filters
616
HTTP header validation
617
Overview
617
Configure HTTP header regular expressions
617
Configure threatening content regular expressions
619
Regular expression format
620
Query string validation
620
Overview
620
Request query string
621
Configure query string attribute regular expressions
621
Configure threatening content regular expressions
623
Regular expression format
623
Validate REST request
624
Overview
624
General settings
624
Add REST request parameter restrictions
625
URI path templates
627
Validate selector expression
628
Overview
628
Configure selector-based regular expressions
628
Configure threatening content regular expressions
629
Validate timestamp
Axway API Gateway 7.5.2
630
Policy Developer Guide 24
Overview
630
Configuration
630
Verify the WS-Policy security header layout
631
Overview
631
Configuration
632
XML complexity
632
Overview
632
Configuration
633
18 Conversion filters
634
Add HTTP header
634
Overview
634
Configuration
635
Add XML node
636
Overview
636
Configuration
636
Examples
638
Convert multipart or compound body type message
640
Overview
640
Configuration
640
Create cookie
640
Overview
640
Configuration
641
Create REST request
641
Overview
641
Configuration
642
Transform with data map
Configuration
Extract MTOM content
643
643
644
Overview
644
Configuration
645
Insert MTOM attachment
645
Overview
645
Configuration
647
Add node to JSON document
647
Overview
647
Configuration
647
Examples
649
Exceptions
651
Remove node from JSON document
652
Overview
652
Configuration
652
Examples
652
Exceptions
654
Axway API Gateway 7.5.2
Policy Developer Guide 25
Convert JSON to XML
654
Overview
654
Configuration
654
Examples
655
Exceptions
657
Load contents of a file
657
Overview
657
Configuration
658
Remove HTTP header
659
Overview
659
Configuration
659
Remove XML node
660
Overview
660
Configuration
660
Exceptions
661
Remove attachments
661
Overview
661
Configuration
661
Restore message
661
Overview
661
Configuration
662
Set HTTP verb
662
Overview
662
Configuration
662
Set message
662
Overview
662
Configuration
663
Example of using selectors in the message body
663
Store message
664
Overview
664
Configuration
664
Convert XML to JSON
664
Overview
664
Configuration
665
Exceptions
666
Transform with XSLT
666
Overview
666
Configuration
666
19 Encryption filters
Generate key
669
669
Overview
669
Configuration
670
JWT decrypt filter
Axway API Gateway 7.5.2
670
Policy Developer Guide 26
Overview
670
General settings
671
Decryption using key selection
671
Shared key selection details
671
JWT encrypt filter
672
Overview
672
General settings
673
Encryption details
673
Asymmetric key details
673
Symmetric key details
674
JWK details
674
FIPS restrictions
675
PGP decrypt and verify
675
Overview
675
Configuration
676
PGP encrypt and sign
678
Overview
678
General settings
679
Encrypt and sign settings
679
Advanced settings
681
SMIME decryption
681
Overview
681
Configuration
681
SMIME encryption
682
Overview
682
General settings
682
Recipient settings
682
Advanced settings
682
XML decryption
683
Overview
683
Configuration
683
Auto-generation using the XML decryption wizard
683
XML decryption settings
684
Overview
684
XML encryption overview
684
Nodes to decrypt
687
Decryption key
688
Options
688
Auto-generation using the XML decryption wizard
689
XML encryption
689
Overview
689
Configuration
690
Auto-generation using the XML encryption settings wizard
690
XML encryption settings
Axway API Gateway 7.5.2
690
Policy Developer Guide 27
XML encryption overview
690
Encryption key settings
693
Key info settings
694
Recipient settings
698
What to encrypt settings
700
Advanced settings
701
Auto-generation using the XML encryption settings wizard
703
XML encryption wizard
703
Overview
703
Configuration
704
20 Fault handling filters
705
Generic error handling
705
Overview
705
General settings
705
Generic error contents
706
Create customized generic errors
706
JSON error handling
707
Overview
707
General settings
707
JSON error contents
708
Create customized JSON errors
710
SOAP fault handling
710
Overview
710
SOAP fault format settings
711
SOAP fault content settings
711
Create Customized SOAP faults
712
21 Integrity filters
JWT Sign
715
715
Overview
715
General settings
716
Signing details
716
Asymmetric key details
716
Symmetric key details
717
JWT Verify
717
Overview
717
General settings
718
Verification using RSA/EC public keys
718
Verification using symmetric key details
718
Sign SMIME message
719
Overview
719
Configuration
719
Verify SMIME message
Axway API Gateway 7.5.2
720
Policy Developer Guide 28
Overview
720
Configuration
720
XML signature generation
720
Signing key settings
721
What to sign settings
727
Where to place signature settings
737
Advanced settings
738
XML signature verification
743
Overview
743
Signature verification settings
744
What must be signed settings
745
Advanced settings
745
22 Monitoring filters
747
Log message payload
747
Overview
747
Configuration
747
Send cycle link event to Sentinel
748
Overview
748
General settings
749
Further information
750
Send event to Sentinel
750
Overview
750
General settings
750
Further information
752
Service level agreement
752
Overview
752
Response time requirements
753
HTTP status requirements
755
Communications failure requirements
756
Select alerting system
756
Set service context
757
Overview
757
General settings
757
Set transaction log level and log message
758
Overview
758
Configuration
758
23 Oracle Access Manager filters
Oracle Access Manager authorization
760
760
Overview
760
General settings
760
Request settings
761
OAM Access SDK settings
761
Axway API Gateway 7.5.2
Policy Developer Guide 29
Oracle Access Manager certificate authentication
762
Overview
762
General settings
762
Resource settings
762
Session settings
763
OAM Access SDK settings
763
Oracle Access Manager SSO session logout
764
Overview
764
Configuration
764
Oracle Access Manager SSO token validation
764
Overview
764
Configuration
765
24 Oracle Entitlements Server filters
Oracle Entitlements Server 10g authorization
766
766
Overview
766
Configuration
766
Get roles from Oracle Entitlements Server 10g
767
Overview
767
Configuration
768
Oracle Entitlements Server 11g authorization
769
Overview
769
Configuration
769
25 Routing filters
Get started with routing configuration
770
770
Overview
770
Proxy or endpoint server
771
Service virtualization
771
Choose the correct routing filters
771
Use case 1: Proxy without service virtualization
772
Use case 2: Proxy with service virtualization
773
Use case 3: Endpoint without service virtualization
774
Use case 4: Endpoint with service virtualization
775
Use case 5: Simple redirect
776
Use case 6: Routing on to an HTTP proxy
777
Summary
778
Call internal service
779
Overview
779
Configuration
779
Connect to URL
780
Overview
780
General settings
780
Request settings
780
Axway API Gateway 7.5.2
Policy Developer Guide 30
SSL settings
781
Authentication settings
782
Additional settings
782
Connection
786
Overview
786
SSL settings
786
Authentication settings
786
Additional settings
786
Dynamic router
787
Overview
787
Extract path parameters
787
Overview
787
Configuration
787
Required input and generated output
788
Possible outcomes
789
File upload
789
Overview
789
General settings
789
File details
790
Connection type
790
File download
792
Overview
792
General settings
792
File details
793
Connection type
793
HTTP redirect
794
Overview
794
Configuration
795
HTTP status code
795
Overview
795
Configuration
796
Insert WS-Addressing information
796
Overview
796
Configuration
796
Read WS-Addressing information
797
Overview
797
Configuration
797
Rewrite URL
798
Overview
798
Configuration
798
Route to SMTP
798
Overview
798
General settings
798
Message settings
799
Axway API Gateway 7.5.2
Policy Developer Guide 31
Save to file
799
Overview
799
Configuration
800
Static router
800
Overview
800
Configuration
801
Route to TIBCO Rendezvous
801
Overview
801
Configuration
801
Wait for response packets
802
Overview
802
Packet sniffer configuration
803
Response packet sniffing
804
25 Security service filters
Encrypt and decrypt web services
806
806
Overview
806
Configuration
806
DSS signature generation
807
Overview
807
Configuration
807
STS web service
807
Overview
807
Configuration
807
DSS signature verification
808
Overview
808
Configuration
808
26 Sun Access Manager filters
810
Sun Access Manager settings
810
Overview
810
Connection settings
810
Output settings
811
General settings
811
Additional properties
811
Sun Access Manager authorization
812
Overview
812
Configuration
812
Sun Access Manager SSO session logout
813
Overview
813
Configuration
813
Retrieve attributes from Sun Access Manager
814
Overview
814
Configuration
815
Axway API Gateway 7.5.2
Policy Developer Guide 32
Sun Access Manager SSO token validation
816
Overview
816
Configuration
817
Sun Access Manager certificate authentication
817
Overview
817
Configuration
817
27 Utility filters
819
Abort policy
819
Overview
819
Configuration
820
Check group membership
820
Overview
820
Configuration
820
Possible results
821
Copy or modify attributes
821
Overview
821
Configuration
821
Evaluate selector
822
Overview
822
Configuration
823
Execute external process
823
Overview
823
Configuration
824
False filter
825
Overview
825
Configuration
825
HTTP parser
825
Overview
825
Configuration
826
Insert BST
826
Overview
826
Configuration
826
Invoke policy per message body
827
Overview
827
Configuration
827
Locate XML nodes
828
Overview
828
Configuration
828
Management services RBAC
830
Overview
830
Configuration
831
Pause processing
831
Overview
Axway API Gateway 7.5.2
831
Policy Developer Guide 33
Configuration
831
Policy shortcut
831
Overview
831
Configuration
832
Policy shortcut chain
832
Overview
832
General settings
832
Add a policy shortcut
833
Edit a policy shortcut
833
Quote of the day
834
Overview
834
Configuration
834
Reflect message
835
Overview
835
Configuration
835
Reflect message and attributes
835
Overview
835
Configuration
836
Remove attribute
836
Overview
836
Configuration
836
Set attribute
836
Overview
836
Configuration
836
Set response status
837
Overview
837
Configuration
837
String replace
837
Overview
837
Configuration
837
Switch on attribute value
838
Overview
838
Configuration
839
Add a switch case
839
Time filter
840
Overview
840
General settings
840
Basic time settings
841
Advanced time settings
842
True filter
842
Overview
842
Configuration
843
Axway API Gateway 7.5.2
Policy Developer Guide 34
28 Web service filters
Return WSDL
844
844
Overview
844
Configuration
844
Set web service context
844
Overview
844
General settings
845
Service WSDL settings
845
Monitoring settings
845
Web service filter
845
Overview
845
General settings
846
Routing settings
846
Validation settings
847
Configure message interception points
848
WSDL settings
850
Monitoring options
852
29 Extend API Gateway filters
Advanced filter view
853
853
Overview
853
Enable advanced filter view
853
Edit filter settings
854
Return to default filter view
854
Select configuration values at runtime
854
Overview
854
Selector syntax
855
Example selector expressions
856
Extract message attributes
858
Scripting language filter
858
Overview
858
Write a custom script
859
Add your script JARs to the classpath
860
Configure a script filter
860
Add a script to the library
861
Further information
862
30 Common settings
Compressed content encoding
863
863
Overview
863
Encoding of HTTP responses
863
Encoding of HTTP requests
864
Delimit the end of an HTTP message
864
Configure content encodings
865
Axway API Gateway 7.5.2
Policy Developer Guide 35
Further information
Configure connection groups
866
866
Overview
866
Configure a connection group
867
Configure a connection
867
Configure cron expressions
868
Overview
868
Create a cron expression using the time tabs
868
Enter a cron expression
872
Test the cron expression
872
Further information
873
Signature location
873
Overview
873
Signature location options
873
Configure URL groups
876
Overview
876
Configure a URL group
876
Configure XPath expressions
877
Overview
877
Manual XPath configuration
877
XPath wizard
879
WS-Policy reference
881
Overview
881
AsymmetricBinding WS-Policies
881
Message-level WS-Policies
882
Oracle Web Services Manager WS-Policies
882
Simple WS-Policies
883
SymmetricBinding WS-Policies
884
TransportBinding WS-Policies
884
License acknowledgments
886
Overview
886
Acknowledgments
886
Axway API Gateway 7.5.2
Policy Developer Guide 36
Preface
This guide describes the main API Gateway features (for example, policies, filters, and configuration options), and how to configure them using the Policy Studio graphical tool.
Who should read this guide
This guide is intended for policy developers.
Familiarity with Axway products is recommended.
How to use this guide
This guide should be used in conjunction with the other guides in the API Gateway documentation set.
Before you begin developing policies, review this guide thoroughly. The following is a brief description of the contents of each section:
Get started on page 40 – Describes how to get started with policy development in Policy Studio.
Manage policies on page 74 – Describes how to configure policies manually, including global policies and policy assemblies.
Web services on page 84 – Describes how to register and secure web services, and how to work with WSDL documents and XML schemas.
Messaging on page 161 – Describes how to configure messaging services.
Manage deployments on page 217 – Describes how to deploy API Gateway configurations.
General configuration on page 179 – Describes general configuration settings available in Policy Studio.
API Gateway instances on page 279 – Describes how to configure API Gateway instances.
External connections on page 371 – Describes how to configure external connections.
Environment configuration on page 230 – Describes how to work with API Gateway resources and libraries.
Policy Studio filters – Filters are divided into filter categories. Each section describes how to configure the filters in that filter category in Policy Studio. Common settings on page 863 – Describes how to configure settings that are common to many API Gateway components.
Axway API Gateway 7.5.2
Policy Developer Guide 37
Preface
Related documentation
The following reference documents are available on the Axway Documentation portal at http://docs.axway.com:
l API Management Concepts Guide
This guide describes how API Gateway, API Manager, and API Portal are used to publish, promote, and manage APIs in a secure and scalable environment.
l API Management Plus Concepts Guide
This guide describes how AxwayAPI Management Plus is used to create APIs from cloud applications and on-premise services, control the use of APIs, and enable self-service consumption of APIs.
l Axway Supported Platforms
Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product.
l Axway Interoperability Matrix
Provides product version and interoperability information for Axway products.
Axway user forums
Post comments and questions to the Axway user forum: http://forums.axway.com/index.php
Support services
The Axway Global Support team provides worldwide 24 x 7 support for customers with active support agreements.
Email [email protected] or visit Axway Support at https://support.axway.com.
See "Troubleshoot your API Gateway installation" in the API Gateway Administrator Guide for the information that you should be prepared to provide when you contact Axway Support.
Training services
Axway offers training across the globe, including on-site instructor-led classes and self-paced online learning. For details, go to: http://www.axway.com/support-services/training
Axway API Gateway 7.5.2
Policy Developer Guide 38
Accessibility
Axway strives to create accessible products and documentation for users. This documentation provides the following accessibility features:
l Screen reader support on page 39
l Support for high contrast and accessible use of colors on page 39
Screen reader support
l Alternative text is provided for images whenever necessary. l The PDF documents are tagged to provide a logical reading order.
Support for high contrast and accessible use of
colors
l The documentation can be used in high-contrast mode.
l There is sufficient contrast between the text and the background color.
l The graphics have the right level of contrast and take into account the way color-blind people perceive colors. Axway API Gateway 7.5.2
Policy Developer Guide 39
Get started
1
This section describes how to get started with policy development in API Gateway.
Policy development with Policy Studio
40
Start the API Gateway tools
47
Create a Policy Studio project
48
Configure the sample policies
52
Conversion sample policy
56
Security sample policies
58
Throttling sample policy
62
Virtualized service sample policy
63
Stress test with send request (sr)
67
Send a request with API Tester
72
Policy development with Policy Studio
Overview
This topic explains some of the main components and concepts used in API Gateway policy development, and shows examples of how they are displayed in the API Gateway management tools such as Policy Studio and API Tester. For example, these include concepts such as filters, policies, message attributes, and listeners. For details on the core API Gateway features and architecture, see the API Management Concepts Guide. For example, this includes concepts such as API Gateway instances, groups, Node Manager, Admin Node Manager, and so on.
Policy Studio projects
A Policy Studio project is a design-time store of API Gateway configuration on a local file system, which can be deployed to a running API Gateway instance on a server. Policy Studio projects enable you to use API Gateway as a design-time repository for policies as well as a runtime engine for executing those policies.
For example, policy developers can create specific API Gateway configuration projects o n their file system, edit the API Gateway policies and other configuration items, and save their changes back to Axway API Gateway 7.5.2
Policy Developer Guide 40
1 Get started
the file system. They can also then deploy their local Policy Studio project configuration to a running API Gateway instance to test those changes. For more details, see Manage Policy Studio projects on page 179.
API Gateway instances and groups
You can use Policy Studio to configure and deploy API Gateway instances and groups. An API Gateway instance is an API Gateway capable of running on a host. You can configure various features at the instance level as listeners (for example, HTTP(S) interfaces, file transfer services, JMS services, remote hosts, and so on). An API Gateway group is a collection of one or more API Gateway instances that share the same configuration. For more details, see the API Management Concepts Guide. Filters
A filter is an executable rule that performs a specific type of processing on a message. For example, the Message Size filter rejects messages that are greater or less than a specified size. There are many categories of message filters available with the API Gateway, including authentication, authorization, content filtering, signing, and conversion. In the Policy Studio, a filter is displayed as a block of business logic that forms part of an execution flow known as a policy. The next section shows some example filters.
Policies
A policy is a network of message filters in which each filter is a modular unit that processes a message. A message can traverse different paths through the policy, depending on which filters succeed or fail. For example, this enables you to configure policies that route messages that pass a Schema Validation filter to a back-end system, and route messages that pass a different Schema
Validation filter to a different system. A policy can also contain other policies, which enables you to build modular reusable policies. In the Policy Studio, the policy is displayed as a path through a set of filters. Each filter can have only one Success Path and one Failure Path. You can use these success and failure paths to create sophisticated rules. For example, if the incoming data matches schema A, scan for attachments and route to service A, otherwise route to service B. You can configure the colors used to display success paths and failure paths in the Policy Studio Preferences menu. You can also specify to Show Link Labels (S or F).
The following shows an example policy that performs XML signature verification:
Axway API Gateway 7.5.2
Policy Developer Guide 41
1 Get started
A policy must have a Start filter (in this case, Verify the Request XML Signature). Filters labeled End stop the execution of the policy (for example, the filter execution fails). A filter labeled Start/End indicates that the policy execution starts there, and that the policy stops executing if this filter fails. A policy with a single filter labeled Start/End is also valid.
Message attributes
Each filter requires input data and produces output data. This data is stored in message attributes, and you can access their values in API Gateway configuration using a selector syntax (for example, ${attribute.name}). You can also use specific filters to create your own message attributes, and to set their values. The full list of message attributes flowing through a policy is displayed when you right-click the Policy Studio canvas, and select Show All Attributes. You can also hover your mouse over a filter to see its inputs and outputs. The Trace filter enables you to trace message attribute values at runtime.
The message attribute white board refers to the list of attributes that are available to a particular filter at runtime of the API Gateway during the processing of requests and responses. The following example shows the attributes displayed when hovering over a Connect to URL filter at design time in Policy Studio:
Axway API Gateway 7.5.2
Policy Developer Guide 42
1 Get started
If a filter requires an attribute as input that has not been generated in the previous execution steps, the filter is displayed in a different color in the Policy Studio (default is red). You can configure the color used to display missing attributes in the Policy Studio Preferences menu. Alternatively, you can also view all required attributes by right-clicking the canvas, and selecting Show All
Attributes.
A missing attribute might indicate a problem that you need to investigate (for example, in the chaining of filters or policies, or that the policy cannot run on its own). This is often the case for reusable filters, such as those displayed in the previous example.
At the policy level, you also can click the horizontal bar at the top of the Policy Studio canvas to show the list of all attributes required as input to the entire policy. If any attributes are generated by the policy, you can click a corresponding bar at the bottom to see a list of generated attributes. The following example shows a required attribute:
Selectors
A selector is a special syntax that enables API Gateway configuration settings to be evaluated and expanded at runtime based on metadata (for example, in message attributes, a Key Property Store (KPS), or environment variables). For example, the following selector returns the value of a message attribute:
${http.request.clientaddr}
Selectors are powerful a feature for System Integrators (SIs) and Independent Software Vendors (ISVs) when extending the API Gateway to integrate with other systems. For more details on selectors, see Select configuration values at runtime on page 854. Axway API Gateway 7.5.2
Policy Developer Guide 43
1 Get started
Faults and errors
When a transaction fails, you can use a fault to return error information to the client application. The API Gateway provides the SOAP Fault, JSON Error, and Generic Error filters. By default, the API Gateway returns a very basic fault to the client when a message filter fails. You can add a specific fault filter to a policy to return more detailed error information to the client. For example, the following screen shows an authentication policy that includes a SOAP Fault:
Policy shortcuts
A policy shortcut enables you to create a link from one policy to another policy. For example, you could create a policy that inserts security tokens into a message, and another that adds HTTP headers. You can then create a third policy that calls the other two policies using Policy Shortcut filters. A policy shortcut chain enables you to run a series of policies in sequence without needing to create a policy containing policy shortcuts. In this way, you can create modular policies to perform certain specific tasks, such as authentication, content filtering, returning faults, or logging, and then link these policies together in a sequence using a policy shortcut chain. Axway API Gateway 7.5.2
Policy Developer Guide 44
1 Get started
Alerts
The API Gateway can send alert messages for specified events to various alerting destinations. System alerts are usually sent when a filter fails, but they can also be used for notification purposes. For example, the API Gateway can send system alerts to the following destinations:
l Email Recipient
l Check Point Firewall-1 (OPSEC)
l Local Sylsog
l Remote Sylsog
l SNMP Network Management System
l Twitter
l Windows Event Log
You can configure alert destinations, and then add an Alert filter to a policy, specifying the appropriate alert destination.
Policy containers
A policy container is used to group similar policies together (for example, all authentication o r logging policies), or policies that relate to a particular service. A number of useful policies are provided in the Policy Library container (for example, policies that return faults, and policies that block threatening content). You can add your own policies to this container, and add your own policy containers to suit your requirements. Policy contexts
Policies can execute in a specified context. For example, you can set a context by associating a relative execution path or listener with a policy. When a policy is called from another policy, the context is set to the calling policy name (for example, Authenticate). In Policy Studio, you can select a context from the Context drop-down list at the bottom of the policy canvas. The Policy Studio then displays whether the attributes required for execution are available in that context. The Context list includes all connected relative paths, listeners, web services, SMTP services, and policy shortcuts that use the selected policy. Click View navigator
node to display the selected context. Listeners
You can define different types of listeners and associate them with specific policies. For example, listeners include the following types:
Axway API Gateway 7.5.2
Policy Developer Guide 45
1 Get started
l HTTP/HTTPS
l Directory Scanner
l POP mail server connection
l JMS connection
l TIBCO Rendezvous connection
The API Gateway can be used to provide protocol mediation (for example, receiving a SOAP request over JMS, and transforming it into a SOAP/HTTP request to a back-end service). For HTTP/HTTPS listeners, policies are linked to a relative path. Otherwise, policies are linked to the listener itself. You can associate a single policy with multiple listeners.
Remote hosts
You can define a remote host when you need more control of the connection settings to a particular server. The available connection settings include the following:
l HTTP version
l IP addresses
l Timeouts
l Buffers
l Caches
For example, by default, the API Gateway uses HTTP 1.0. You can force it to use HTTP 1.1 using remote host settings. You must also define a remote host to track real-time metrics for a particular host.
Servlet applications
The API Gateway provides a web server and servlet application server that can be used to host static content (for example, documentation), or servlets providing internal services. Static content or servlets can be accessed from a policy using the Call Internal Service filter. This feature is not meant to replace an enterprise J2EE server, but rather to enable you to write functionality using technology such as servlets.
Service virtualization
When you register an API service or web service, and deploy it to the API Gateway, the API Gateway virtualizes the service. Instead of connecting to the service directly, clients connect through the API Gateway. The API Gateway can then apply policies to messages sent to the destination service (for example, to enable security, monitoring, and acceleration).
Axway API Gateway 7.5.2
Policy Developer Guide 46
1 Get started
Start the API Gateway tools
Overview
This topic describes the prerequisites and preliminary steps. It explains how to start the API Gateway Manager administrator tool and the Policy Studio developer tool. Before you begin
Before you start the API Gateway tools, do the following:
Install the API Gateway and Policy Studio
If you have not already done so, see the API Gateway Installation Guide. Configure a managed domain
If you have not already created a domain, use the managedomain script to configure a domain. You should ensure that the Admin Node Manager and an API Gateway instance are running. For more information on managing domains, see the API Gateway Administrator Guide.
Launch API Gateway Manager
To access the web-based API Gateway Manager administration tools, perform the following steps:
Note
You must ensure that the Admin Node Manager is running before you can access the webbased API Gateway Manager tools.
1. Enter the following URL: https://HOST:8090/
HOST refers to the host name or IP address of the machine on which the API Gateway is running (for example, https://localhost:8090/). 2. Enter the administrator user name and password configured at installation time.
3. Click the appropriate button in the API Gateway Manager page in the browser. The Dashboard view is displayed by default.
The API Gateway Manager includes the following main views:
Axway API Gateway 7.5.2
Policy Developer Guide 47
1 Get started
l Dashboard: System health, traffic summary, and topology (domain, hosts, API Gateways, and groups).
l Traffic: Message log and performance statistics on the traffic processed by the API Gateway. For example, all HTTP, HTTPS, JMS, File Transfer, and Directory messages processed by the API Gateway.
l Monitoring: Real-time monitoring of all the traffic processed by the API Gateway. Includes statistics at the system level and for services invoked and remote hosts connected to. l Logs: API Gateway trace log, transaction log, and access log files.
l Events: API Gateway transaction log points, alerts, and SLA alerts.
l Settings: Enables you to configure dynamic API Gateway logging, user roles, and credentials.
For more information on administering API Gateway, see the API Gateway Administrator Guide.
Start Policy Studio
To start the Policy Studio tool used to create and manage policies, perform the following steps:
1. In your Policy Studio installation directory, enter the policystudio command.
2. In Policy Studio, select File > New Project, and follow the steps in the wizard. For more details, see Create a Policy Studio project on page 48.
Alternatively, if a project has already been created, select File > Open Project, or click a link to the existing project on the Policy Studio landing page. For more details, see Manage API Gateway connections on page 182.
Policy Studio enables you to perform the full range of API Gateway configuration and management tasks. This includes tasks such as develop and assign policies, import services, optimize API Gateway configuration settings, and manage API Gateway deployments. For more details on using the Policy Studio to manage API Gateway processes and configurations, see Manage API Gateway deployments on page 217.
Create a Policy Studio project
Overview
This topic explains how to create a new Policy Studio project from the following starting points:
l Template configuration (for example, factory)
l Deployment package ( .fed file)
l Policy and environment packages ( .pol and . env files)
Axway API Gateway 7.5.2
Policy Developer Guide 48
1 Get started
l API Gateway instance
l Existing API Gateway configuration
For details on opening an existing project, see Manage API Gateway connections on page 182.
Launch the New Project wizard
To launch the New Project wizard in Policy Studio, select File > New Project in the main menu. Alternatively, click New Project on the welcome page.
Enter project details
Enter the following in the Project Details screen:
l Name: Enter the Policy Studio project name. This field is required.
l Use default location: Select whether to use the default location. This is selected by default.
l Location: Enter or browse to the project location (for example, C:\Users\jane\apiprojects\my_test_project). When Use default location is selected, the default location is ${user.home}/apiprojects/${project.name}.
Click Next.
Select a project starting point
Select one of the following in the Project starting point window:
l From a template configuration
l From a .fed file
l From .pol and .env files
l From an API Gateway instance
l From existing configuration
Choose a template configuration
To create a project based on template configuration:
1. Select the configuration template to use as a starting point:
l Common Project (with Server Settings): Blank template that contains Server Settings. This is for creating your main common project only. This should include policies common to multiple API projects (for example, authentication and authorization).
Axway API Gateway 7.5.2
Policy Developer Guide 49
1 Get started
l API Project (without Server Settings):
Blank template that does not contain Server Settings. This is for creating all your projects (except your main common project). l Factory template (Common Project with Samples):
Blank template that contains sample policies and Server Settings. This is for creating a project used for demo purposes.
2. Click Finish.
Note
The following restrictions apply:
l Your API Gateway configuration must contain only one project with Server Settings. All other projects must have no Server Settings. l There is no project template forAPI Manager configuration. For more details, see Create API Manager projects on page 52.
For more details on common and API projects, see the API Gateway DevOps Deployment Guide.
Choose a .fed file
To create a project based on a deployment package ( .fed file):
1. Configure the following:
l File: Enter or browse to the location of an API Gateway deployment package ( .fed file). For more details, see the API Gateway DevOps Deployment Guide. l Passphrase: Enter the encryption passphrase for the .fed file if one has been configured. For details on configuring passphrases, see Change the project passphrase on page 180.
2. Click Finish.
Choose policy package (.pol) file
To create a project based on a policy package ( .pol file):
1. Configure the following:
l Policy Package: Enter or browse to the location of an API Gateway policy package ( .pol file). This is required.
l Environment Package: Enter or browse to the location of an API Gateway environment package ( .env file). This is optional. l Passphrase: Enter the encryption p assphrase if one has been configured. For details on configuring passphrases, see Change the project passphrase on page 180.
l Advanced: Click to expand, and select whether to Allow unresolved references in
policy package. This setting is optional.
2. Click Finish.
Axway API Gateway 7.5.2
Policy Developer Guide 50
1 Get started
For more details on policy packages and environment packages, see the API Gateway DevOps Deployment Guide.
Open connection to API Gateway instance
To create a project based on an API Gateway instance:
1. In the Saved Sessions section, select the server session to use from the list. You can edit a session name by entering a new name and clicking Save. You can also click the appropriate button to Add, Clone, or Remove saved sessions.
2. In the Connection Details section, configure the following:
l Host:
Enter the server host to connect to. The default is localhost.
l Port:
Enter the port to connect on. The default Admin Node Manager port is 8090.
l User name:
The deployment service is protected by HTTP basic authentication. Enter the administrator user name to use to authenticate to the server. For more details, see Manage admin users on page 226.
l Password:
Enter the password for the administrator user.
3. Click Advanced to enter the URL of the deployment service exposed by the server. This setting is optional. The default Admin Node Manager URL is https://localhost:8090/api.
4. Click Next to download the configuration from the server instance.
If advisory warnings are configured, you must click Next again before downloading the configuration. For more details on advisory warnings, see the API Gateway Administrator Guide.
5. Configure the following in the Make a server connection window:
l Group:
Select the API Gateway group from the list (for example, QuickStart Group), and select the server instance in the panel below (for example, QuickStart Server).
l Passphrase:
Enter the API Gateway passphrase if one has been configured. For details on configuring passphrases, see Change the project passphrase on page 180.
6. Click Finish.
Note
To manage API Gateways in your network, you must connect to the Admin Node Manager server URL.
Choose a configuration directory
To create a project based on an existing configuration directory:
Axway API Gateway 7.5.2
Policy Developer Guide 51
1 Get started
1. Configure the following:
l File: Enter or browse to the location of the configuration directory (for example, INSTALL_DIR\apigateway\conf\fed is the Admin Node Manager configuration directory).
l Passphrase: Enter the encryption p assphrase if one has been configured. For details on configuring passphrases, see Change the project passphrase on page 180.
2. Click Finish.
Create API Manager projects
To create a p roject with API Manager configuration, perform the following steps:
1. Run setup-apimanager on a default API Gateway installation. For more details, see the API Manager API Management Guide.
2. Create a project from an API Gateway instance.
Alternatively, if you already have API Manager configured you can create the project from the existing API Gateway configuration directory.
Note
There is no project template currently available for API Manager configuration.
Upgrade of configuration from previous versions
If you create a project from a .fed file, a .pol file, or a configuration directory from an earlier API Gateway version, the configuration is automatically upgraded to API Gateway 7.5.2 when the new project is created. The configuration directory can be from an API Gateway, Admin Node Manager, or API Gateway Analytics instance.
Note
This feature does not apply when creating a project from an API Gateway instance. You can only download configuration from an API Gateway instance if the Policy Studio version is the same as the API Gateway version.
For more details on upgrading, see the API Gateway Upgrade Guide.
Configure the sample policies
Overview
This topic introduces and explains how to set up the example policies available in the samples directory of your API Gateway installation. These include the following:
Axway API Gateway 7.5.2
Policy Developer Guide 52
1 Get started
l Conversion: exposes a SOAP service over REST.
l Security:
o Verifies the digital signature on the request and creates a signature on the response.
o Decrypts the request and encrypts part of the response.
l Throttling: limits the number of calls for a service.
l Virtualized Service: combines threat protection, content-based routing (target a server according to request contents), and message transformation.
Tip
If you are new to the API Gateway, you should first read the following to get familiar with the main concepts and basic steps:
l API Management Concepts Guide
l Policy development with Policy Studio on page 40
l Start the API Gateway tools on page 47
This guide assumes that you have already installed and started the API Gateway and P olicy Studio. The API Tester client GUI testing tool is optional.
Enable the sample services interface
The HTTP interface for the sample policy services is disabled by default. To enable this interface in Policy Studio, perform the following steps:
1. In the navigation tree, select Environment Configuration > Listeners > API Gateway > Sample Services > Ports.
2. In the Interfaces pane on the right, select *:${env.PORT_SAMPLE_SERVICES}.
3. Right-click, and select Edit to display the Configure HTTP Interface dialog.
4. Select the Enable interface setting.
5. Click OK.
Axway API Gateway 7.5.2
Policy Developer Guide 53
1 Get started
Alternatively, you can also enable this HTTP interface using the web-based API Gateway Manager tool running on http://HOST:8090, where HOST is the machine on which the Node Manager is running.
1. Click the Settings button in the API Gateway Manager toolbar.
2. Select the HTTP interface node under Sample Services on the left.
3. Select the Interface Enabled setting on the right.
4. Click the Apply button.
Note
Settings made in the web-based API Gateway Manager tool are dynamic settings only, which are not persisted.
Configure a different sample services interface
All sample policy services are defined in an HTTP services group named Sample Services. This group uses an HTTP interface running on the port specified in the ${env.PORT_SAMPLE_
SERVICES} environment variable. This external environment variable is set to 8081 by default. To use a different port, you must configure this variable in the INSTALL_
DIR/conf/envSettings.props file. For example, you could add the following entry:
env.PORT.SAMPLE.SERVICES=8082
For more details on setting external environment variables for API Gateway instances, see the API Gateway DevOps Deployment Guide.
StockQuote demo service
All sample policies use a demo service named StockQuote, which is implemented using a set of policies. This service exposes two operations:
l getPrice: the policy for this operation uses a sample script to randomly calculate a quote value. Each call to getPrice() returns a different value.
l update: returns an Accepted HTTP code (202).
The StockQuote service is exposed on the following relative paths:
l /stockquote/instance1
l /stockquote/instance2
These relative paths are used in the virtualized service sample for content-based routing.
A Connect to URL filter with the following URL is used to invoke the StockQuote service from each of the sample policies:
http://stockquote.com/stockquote/instance1
Axway API Gateway 7.5.2
Policy Developer Guide 54
1 Get started
The first part of this URL uses a remote host definition of stockquote.com. Remote hosts are logical names that decouple the host name in a URL from the server (or group of servers) that handles the request. Remote host settings
In Policy Studio, the remote host configuration is displayed under the API Gateway instance name ( API Gateway) in the navigation tree, and is named stockquote.com:80. To view its settings, right-click, and select Edit to view the Remote Host Settings dialog:
On the General tab, the remote host is set to:
l Use HTTP 1.1.
l Use port 80 by default.
l Include the ContentLength header in the request to the back-end server.
l In case of an SSL connection, verify the Distinguished Name (DN) in the certificate presented by the server against the server’s host name.
On the Addresses and Load Balancing tab, the remote host is set to send requests to localhost:${env.PORT_SAMPLE_SERVICES}, which resolves to localhost:8081 by default. You could also specify several servers in the Addresses to use instead of DNS lookup list, and the API Gateway would load balance the requests across servers in the same group using the specified algorithm. Axway API Gateway 7.5.2
Policy Developer Guide 55
1 Get started
For more details on these settings, see Configure remote host settings on page 283.
Conversion sample policy
Overview
The conversion sample policy takes a REST-style request and converts it into a SOAP call. This topic describes the REST to SOAP policy, and explains how to run this sample.
REST to SOAP policy
The REST to SOAP policy is as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 56
1 Get started
The REST to SOAP policy performs the following tasks:
1. Extracts the information from the request (a message attribute is created for each query string and/or HTTP header).
2. Creates a SOAP message using the Set Message filter.
3. Sends the request to the StockQuote demo service.
4. Extracts the value of the stock from the response using XPath.
5. Creates a plain text response.
6. Sets the HTTP status code to 200.
Run the conversion sample
You can call the sample service using the send request ( sr) command or the API Tester GUI:
sr command
Enter the following command:
sr http://HOSTNAME:8081/rest2soap?symbol=ABC
For more details, see Stress test with send request (sr) on page 67.
Axway API Gateway 7.5.2
Policy Developer Guide 57
1 Get started
API Tester
Perform the following steps:
1. Specify the following URL in the Request Settings:
http://HOSTNAME:8081/rest2soap?symbol=ABC
2. Select GET as the verb.
3. Click the Run button.
For more details, see the topic on Send a request with API Tester on page 72.
Security sample policies
Overview
The security sample policies demonstrate digital signature verification and cryptographic operations (encryption and decryption). This topic describes the sample policies, and explains how to run these samples.
Signature verification
The Signature Verification sample policy sends a digitally signed version of the StockQuote request to the API Gateway. The message carries the signature into the web service header. A sample certificate/key pair ( Samples Test Certificate) is used to sign the message and verify the signature. Signature verification is used for authentication purposes, and therefore an HTTP 403 error code is returned if a problem occurs.
The Signature Verification policy is as follows:
The Signature Verification policy performs the following tasks:
Axway API Gateway 7.5.2
Policy Developer Guide 58
1 Get started
1. The signature contained in the request is verified. The signature must be located in a WSSecurity block.
2. If the verification is successful, the StockQuote demo service is invoked.
3. The response body is signed and returned to the client.
4. If the verification fails, an HTTP 403 error code is returned to the client.
Run the signature verification sample
You can call the sample service using the send request ( sr) command or the API Tester GUI:
sr command
Enter the following command:
sr -f INSTALL_DIR/samples/SamplePolicies/Security/SignatureVerification/Request.xml
http://localhost:8081/signatureverification
For more details, see the topic on Stress test with send request (sr) on page 67.
API Tester
Perform the following steps:
1. Specify the following URL in the Request Settings:
http://HOSTNAME:8081/signatureverification
2. Select POST as the Verb.
3. Click the Close button.
4. Select File > Load, and browse to the following file as input for the request:
INSTALL_DIR/samples/SamplePolicies/Security/SignatureVerification/Request.xml
5. Click the Send Request button.
For more details, see the topic on Send a request with API Tester on page 72.
Encryption and decryption
This sample uses XML decryption on the request and applies encryption on the response. The sample policy includes a Main policy, which chains together the calls that decrypt the request, the invocation of the back-end service, and the encryption of the response.
Axway API Gateway 7.5.2
Policy Developer Guide 59
1 Get started
The Main policy is as follows:
The Main policy performs the following tasks:
1. Decrypt Request is a policy shortcut, which invokes another policy that takes the inbound request and decrypts it.
2. The decrypted request is routed to the back-end service.
3. The Encrypt Response policy shortcut invokes a policy that encrypts the response from the back-end service.
The Decrypt policy is as follows:
The Decrypt policy performs the following tasks:
1. The decryption settings are defined: what to decrypt and which key to use.
2. The XML decryption is executed based on the defined settings.
The Encrypt policy is as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 60
1 Get started
The Encrypt policy performs the following tasks:
1. The encryption settings are defined: what to encrypt, which symmetric key to use, which certificate to use, and how to encrypt (algorithm and where to place the encryption information).
2. The XML encryption is executed based on the defined settings.
Run the encryption and decryption sample
You can call the sample service using the send request ( sr) command or the API Tester GUI:
sr command
Enter the following command:
sr -f INSTALL_DIR/samples/SamplePolicies/Security/Encryption/Request.xml
http://HOSTNAME:8081/encryption
For more details, see the topic on Stress test with send request (sr) on page 67.
API Tester
Perform the following steps:
1. Specify the following URL in the Request Settings:
http://HOSTNAME:8081/encryption
2. Select POST as the Verb.
3. Click the Close button.
4. Select File > Load, and browse to the following file as input for the request:
INSTALL_DIR/samples/SamplePolicies/Security/Encryption/Request.xml
5. Click the Send Request button.
For more details, see the topic on Send a request with API Tester on page 72.
Axway API Gateway 7.5.2
Policy Developer Guide 61
1 Get started
Throttling sample policy
Overview
The throttling sample policy is used to limit the number of calls for a service. This topic describes the Throttle policy, and explains how to run this sample.
Throttling refers to restricting incoming connections and the number of messages to be processed. It can be applied to XML, SOAP, REST, or any payload, request, or protocol. Traffic can be regulated for a single API Gateway or for a cluster of API Gateways. You can apply traffic restrictions rules for a service, an operation, or even time of day. For example, these restrictions can be applied depending on the service name, user identity, IP address, content from the payload, protocol headers, and so on.
Throttling policy
The Throttle policy is as follows:
The Throttle policy performs the following tasks:
1. The first filter checks whether the limit has been reached. The limit is set to 3 requests per 15 sec. The caller’s IP address is used to track the consumer ID. The counter is kept in a local cache.
2. If the limit has been reached, an error message is created, and the response status code is set to 500.
3. If the authorized limit has not been reached, the back-end service is invoked, and the HTTP status code is set to 200.
Run the throttling sample
You can call the sample service using the send request ( sr) command or the API Tester GUI:
Axway API Gateway 7.5.2
Policy Developer Guide 62
1 Get started
sr command
Enter the following command:
sr -f INSTALL_DIR/samples/SamplePolicies/Throttling/Request.xml
http://HOSTNAME:8081/throttle
For more details, see the topic on Stress test with send request (sr) on page 67.
API Tester
Perform the following steps:
1. Specify the following URL in the Request Settings:
http://HOSTNAME:8081/throttle
2. Select POST as the Verb.
3. Click the Close button.
4. Select File > Load, and browse to the following file as input for the request:
INSTALL_DIR/samples/SamplePolicies/Throttling/Request.xml
5. Click the Send Request button.
For more details, see the topic on Send a request with API Tester on page 72.
Virtualized service sample policy
Overview
The virtualized service sample policy is more advanced and combines the following features:
l Content filtering, XML complexity, and message size filters to block unwanted SOAP messages.
l Content filtering to block unwanted REST requests.
l Fault handling.
l Content-based routing.
This topic describes the policies displayed in the Sample Policies > Web Services >
Virtualized StockQuote Service policy container in Policy Studio, and explains how to run this sample.
Axway API Gateway 7.5.2
Policy Developer Guide 63
1 Get started
Virtualized service policies
The Virtualized StockQuote Service sample policy container includes the following policies:
l Virtualized service main policy
l Threat protection policy
l Content-based routing policies
l Response transformation policy
The Main Policy is as follows:
The Main Policy uses policy shortcuts to perform the following tasks:
1. The main fault handler relies on some variables to be initialized, which is performed as soon as the policy is entered.
2. The Threat Detection policy is applied to the incoming SOAP message and HTTP headers.
3. The symbol value is extracted from the incoming message, and used to decide whether the request should be sent to one server instance or another.
4. The name of the instance that served the request is added to the response.
5. In case of errors, a global fault handler is invoked. This is used to return a custom error message to the user.
The Threat Protection policy is as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 64
1 Get started
The Threat Protection policy performs the following tasks:
1. The incoming request size (including attachments) is checked to be less than 1500 KB.
2. The complexity of the XML is checked in terms of number of nodes, attributes per node, or number of child nodes per node.
3. XML and eventually HTTP headers are checked for threatening content such as SQL injection or XML processing instructions.
4. If any of these filters return an error, the corresponding error handler is called. The error handler is implemented as a policy that sets the value of the error code and message for this error, and then re-throws the exception so that the global fault handler catches it.
Content-based routing policies
The Route Based on Symbol Value policy extracts the contents of the symbol XML node and checks whether the first letter’s value is between A-L or K-Z. Depending on the result, it routes the request to the first or second instance of the StockQuote server. These servers are simulated by the following relative path URIs defined in the API Gateway:
l /stockquote/instance1
l /stockquote/instance2
The Route Based on Symbol Value policy is as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 65
1 Get started
The Route Based on Symbol Node policy performs the following tasks:
1. The value of the symbol node is extracted from the request using XPath. The result is placed in a message attribute named message.symbol.value.
2. A Switch on attribute value filter is used to check the value of the message attribute (using a regular expression), and a different policy is called to send the request to instance1 or instance2.
The Route to Instance1 policy is as follows:
The Route to Instance1 policy (called from the Switch filter) performs the following tasks:
1. Connects to the instance1 URI.
2. If successful, the instance name ( instance1) is placed in a message attribute ( stockquote.instance.name). This is used later on to insert the instance name into the response.
The Route to Instance2 policy performs the same tasks but using the instance2 URI instead. Response transformation policy
When the response is obtained from the back-end server, the Add Instance Name to Response policy changes it to insert the instance name into a new XML node ( instanceName). The Add
Instance Name to Response policy is as follows:
This policy adds the instance name (the value of the stockquote.message.name message attribute) to the response, using an Add XML node filter, as part of the SOAPbody. XPath is used to define where the new node must be added.
Axway API Gateway 7.5.2
Policy Developer Guide 66
1 Get started
Run the virtualized service sample
You can call the sample service using the send request ( sr) command or the API Tester GUI:
sr command
Enter the following command:
sr -f INSTALL_DIR/samples/SamplePolicies/VirtualizedService/Request.xml
http://HOSTNAME:8081/main/stockquote
For more details, see the topic on Stress test with send request (sr) on page 67.
API Tester
Perform the following steps:
1. Specify the following URL in the Request Settings:
http://HOSTNAME:8081/main/stockquote
2. Select POST as the Verb.
3. Click the Close button.
4. Select File > Load, and browse to the following file as input for the request:
INSTALL_DIR/samples/SamplePolicies/VirtualizedService/Request.xml
5. Click the Send Request button.
For more details, see the topic on Send a request with API Tester on page 72.
Stress test with send request (sr)
Overview
The API Gateway provides a command-line tool for stress testing named send request ( sr). The sr tool is available in the following directory of your API Gateway installation:
Windows
INSTALL_DIR\Win32\lib
UNIX/Linux
INSTALL_DIR/posix/lib
Axway API Gateway 7.5.2
Policy Developer Guide 67
1 Get started
The sr tool is also available from the root directory of the API Tester installation. Note
On Linux, the LD_LIBRARY_PATH environment variable must be set to the directory from which you are running the sr tool. On UNIX/Linux, you must use the vrun sr command. For example:
vrun sr http://testhost:8080/stockquote
Basic sr command examples
The following are some basic examples of using the sr command:
HTTP GET:
sr http://testhost:8080/stockquote
POST file contents (content-type inferred from file extension):
sr -f StockQuoteRequest.xml http://testhost:8080/stockquote
Send XML file with SOAP Action 10 times:
sr -c 10 -f StockQuoteRequest.xml http://testhost:8080/stockquote
Send XML file with SOAP Action 10 times in 3 parallel clients:
sr -c 10 -p 3 -f StockQuoteRequest.xml http://testhost:8080/stockquote
Send the same request quietly:
sr -c 10 -p 3 -qq -f StockQuoteRequest.xml http://testhost:8080/stockquote
Run test for 10 seconds:
sr -d 10 -qq -f StockQuoteRequest.xml http://testhost:8080/stockquote
POST file contents with SOAP Action:
sr -f StockQuoteRequest.xml -A SOAPAction:getPrice http://testhost:8080/stockquote
Advanced sr command examples
The following are some advanced examples of using the sr command:
Axway API Gateway 7.5.2
Policy Developer Guide 68
1 Get started
Send form.xml to http://192.168.0.49:8080/healthcheck split at 171 character size,
and trickle 200 millisecond delay between each send with a 200 Content-Length
header:
sr -h 192.168.0.49 -s 8080 -u /healthcheck -b 171 -t 200 -f form.xml
-a "Content-Type:application/x-www-form-urlenprogramlistingd" -a "ContentLength:200"
Send a multipart message to http://192.168.0.19:8080/test, 2 XML docs are
attached to message:
sr -h 192.168.0.49 -s 8080 -u /test -{ -a Content-Type:text/xml -f soap.txt
-a Content-Type:text/xml -f attachment.xml -a Content-Type:text/xml -} -A ctimestamp:1234
Send only headers using a GET over one-way SSL running 10 parallel threads for
86400 seconds (1 day) using super quiet mode:
sr -h 192.168.0.54 -C -s 8443 -u /nextgen -f test_req.xml -a givenName:SHViZXJ0
-a sn:RmFuc3dvcnRo -v GET -p10 -d86400 -qq
Send query string over mutual SSL presenting client certificate and key doing a GET
running 10 parallel threads for 86400 seconds (1 day) using super quiet mode:
sr -h 192.168.0.54 -C -s 8443 -X client.pem -K client.key
-u "https://localhost:8443/idp?TargetResource=http://axway.test.com" -f test_req.xml
-v GET -p10 -d86400 -qq
Send zip file in users home directory to testhost on port 8080 with /zip URI, save the
resulting response content into the result.zip file, and do this silently:
sr -f ~/test.zip -h testhost -s 8080 -u /zip -a Content-Type:application/zip
-J result.zip -qq
sr command arguments
The main arguments to the sr command include the following:
Argument
Description
--help
List all arguments
-a
Set the HTTP request header (for example, -a Content-
attribute:value
Type:text/xml)
Axway API Gateway 7.5.2
Policy Developer Guide 69
1 Get started
Argument
Description
-c [request-
Number of requests to send per process
count]
-d [seconds]
Duration to run test for
-f [content-
File to send as the request
filename]
-h [host]
Name of destination host
-i [filename]
Destination of statistics data
-l [file]
Destination of diagnostic logging
-m
Recycle SSL sessions (use multiple times)
-n
Enable nagle algorithm for transmission
-o [output]
Output statistics information every [milliseconds] (only with -d)
-p
Number of parallel client connections (threads) to simulate
[connections]
-q , -qq, -qqq
Quiet modes (quiet, very quiet, very very quiet)
-r
Do not send HTTP Request line
-s [service]
Port or service name of destination (default is 8080)
-t
Trickle: delay between sending each character
[milliseconds]
-u [uri]
Target URI to place in request
-v [verb]
Set the HTTP verb to use in the request (default is POST)
-w
Wait for [milliseconds] between each request
[milliseconds]
-x [chunksize]
Chunk-encode output
-y [cipherlist]
SSL ciphers to use (see OpenSSL manpage ciphers(1))
Axway API Gateway 7.5.2
Policy Developer Guide 70
1 Get started
Argument
Description
-z
Randomize chunk sizes up to limit set by -x
-A
Set the HTTP request header (for example, -a Content-
attribute:value
Type:text/xml) in the outermost attachment
-B
Buckets for response-time samples
-C
enCrypt (use SSL protocol)
-I [filename]
File for Input (received) data ( - = stdout)
-K
RSA Private Key
-L
Line-buffer stdout and stderr
-M
Multiplier for response-time samples
-N
origiN for response-time samples
-O [filename]
File for Output (sent) data ( - = stdout)
-S [part-id]
Start-part for multipart message
-U [count]
reUse each connection for count requests
-V [version]
Sets the HTTP version ( 1.0, 1.1)
-X
X.509 client certificate
-Y [cipherlist]
Show expanded form of [cipherlist]
[-{/-}
Create multipart body (nestable: use -f for leaves)
Further information
For a listing of all arguments, enter sr --help. Axway API Gateway 7.5.2
Policy Developer Guide 71
1 Get started
Send a request with API Tester
Overview
This topic describes how to create and send a request in the API Tester test client GUI. You can start API Tester using the apitester command from the installation directory. Create a request in API Tester
To create a request, perform the following steps:
1. Click the down arrow button beside the Send Request button in the toolbar, and select Request Settings:
2. In the Request Settings dialog, click the Add Request button in the toolbar:
3. Enter the details for the request to execute in the Add Request Configuration dialog. For example, enter http://localhost:8080/conversion in the URL field. If the Request name matches URL setting is not selected, you can supply a custom Request
Name for this request. Click OK to save the request configuration.
Axway API Gateway 7.5.2
Policy Developer Guide 72
1 Get started
4. Click the down arrow button beside the Send Request button in the toolbar, and select the request that you created in the Select Request Configuration menu:
5. In the main menu, select File >Load Request, and browse to the file to use as input for this request. For example, you can select the following file for the Virtualized Service sample:
INSTALL_DIR/samples/SamplePolicies/VirtualizedService/Request.xml
6. Click the Send Request button in the toolbar to send the request.
Further information
For more details on using the API Tester client GUI tool, see the API Tester online help.
Axway API Gateway 7.5.2
Policy Developer Guide 73
Manage policies
2
This section describes how to manage API Gateway policies.
Configure policies manually
74
Configure global policies
76
Configure policy assemblies
81
Configure policies manually
Overview
This topic describes how to use Policy Studio to configure an API Gateway policy manually. It also applies to cases where a web service definition is not available in a Web Services Description Language (WSDL) file, meaning that the policy used to protect a web service must be configured manually. However, the recommended way to configure a policy to protect a web service is to import the WSDL file for that service. If WS-Policy information is contained in the WSDL file, the policy assertions can also be used to produce a complex policy with minimum effort for administrators. If your web service has WSDL-based definitions, see Configure policies from WSDL files on page 86.
Configuration
The following steps outline how to manually create a policy to protect a web service and then test it.
Step 1: Create the policy
To create a policy manually, complete the following steps:
1. Right-click the Policies node in the Policy Studio tree, and select the Add Policy menu option.
2. Enter a suitable name (for example TestPolicy) for the new policy in the Name field, and click the OK button. The new policy is now visible in the tree.
3. Click the new policy in the tree to start configuring the filters for the policy. You can easily configure the policy by dragging the required filters from the filter palette on the right of Policy Studio, and dropping them on to the policy canvas. Axway API Gateway 7.5.2
Policy Developer Guide 74
2 Manage policies
Most policies attempt to check characteristics of the message, such as message size and format, and attempt to authenticate or authorize the sender of the message. When the message successfully passes all configured filters, it is usually routed on to the protected web service. For demonstration purposes, this example creates a simple policy consisting of two filters. The first filter checks the size of the message, and the second echoes the request message back to the client if it is below a certain size.
4. Expand the Content Filtering category of filters from the filter palette, and drag and drop the Message Size filter on to the canvas.
5. Enter 10 in the At least field and 1000 in the At most field to make sure that only messages between 10 bytes and 1000 bytes are reflected back to the client. Select all other defaults, and click the Finish button.
6. Right-click the newly added filter, and select the Set as Start menu option to indicate that this is the first filter to be executed in this policy. The icon for the filter changes to indicate that it is the start of the policy.
7. Open the Utilities category of filters, and drag the Reflect filter onto the canvas. Drop it on to the previously configured Message Size filter. Select the defaults for the Reflect filter, and click the Finish button. Because you dropped the Reflect filter on to the Message Size filter, both filters are automatically linked with a success path. This means that if the first filter runs successfully, the next filter on the success path is executed. To link in more filters, add the filters to the canvas, and click the Success Path button at the top of the palette. Click the first filter followed by the second filter in the success path to link both filters. You can also configure failure paths for filters in the same way. Failure paths are followed when the checks configured in the filter fail.
This completes the configuration of the simple policy.
Step 2: Create a new relative path
You must now create a Relative Path on the API Gateway instance, which maps incoming requests on a particular URI to the new policy. Complete the following steps:
1. In the Policy Studio tree, select Environment Configuration > Listeners > API Gateway.
2. Right-click the Default Services node, and select Add Relative Path.
3. On the Configure Relative Path dialog, enter a suitable URI (for example, TestPolicy) on which to receive requests that are to be processed by the new policy. 4. To map requests received on this URI to our new policy, select the /TestPolicy p olicy from the list of policies in the tree. Click the OK button when finished. Axway API Gateway 7.5.2
Policy Developer Guide 75
2 Manage policies
Step 3: Deploy to API Gateway
Before the new configuration changes can take effect, you must deploy them to API Gateway. You can do this by clicking the Deploy button on the right of the toolbar. Alternatively, press the F6 key. Step 4: Test the policy
You can use the tool of your choice (for example, Axway API Tester) to send SOAP requests to the new policy. You should send requests of different sizes to the following URL, assuming a default installation of API Gateway running on the local machine:
http://localhost:8080/TestPolicy
Request messages that fall between the configured size are reflected to the client. Those that fall outside of the configured size are blocked, and a SOAP Fault is returned to the client. Step 5: Next steps
Try running more complicated checks on request messages by adding new filters to the TestPolicy. Try also adding failure paths to the original Message Size filter to handle messages that fall outside of the 10-1000 byte range. Use the Help button on each filter window to find out more about the configuration fields that are available on each window. Configure global policies
Overview
Global policies enable you to label policies with specific roles in the API Gateway configuration. For example, you can label a specific policy such as XML Threat Policy as a Global Request policy. This policy can be executed globally on the request path for all messages passing through API Gateway. Using a global policy in this way enables you to use the same policy on all requests, and for multiple services. It also means that you can change the labeled global policy to a different policy without needing to rewire any existing policies.
For example, using a Policy Shortcut Chain filter in a policy enables you to delegate to one or more policies to perform specific tasks, before continuing execution of the remaining filters in the Axway API Gateway 7.5.2
Policy Developer Guide 76
2 Manage policies
current policy. Using this approach to encapsulate specific functionality in a policy facilitates modularity and reusability when designing API Gateway policies. This enables you to build up a policy library of reusable routines over time.
Each shortcut in a Policy Shortcut Chain points to a specific policy, which is called at each point in the execution chain. However, consider a policy whose role is to be called first in all message handling contexts before any context-specific policies are run, and call this the run-first role. To realize this, you must create a Policy Shortcut Chain with a link to the run-first policy as its first entry, the context-specific policy as its second link, and so on. One of the shortcomings of this approach is that if you have set up a large number of Policy
Shortcut Chain filters, each calling the run-first policy, and you need to change the run-first policy globally, you must update each Policy Shortcut Chain filter individually to point to the newly designated run-first policy. Similarly, if you wish to ignore the run-first Policy globally, you must remove the first entry in each filter.
Global policies enable you to label a specific policy in terms of its role. You can delegate to the policy using its label instead of a specific link to the policy. This indirection using a label makes it very easy to globally change which policy is delegated to, merely by moving the label from one policy to another. Each filter that refers to the policy using its label now resolves the label to the new policy without needing to change the filter configuration. Similarly, if the label is not applied to a specific policy, nothing is executed for this link.
Global policy roles
The following global policy roles have a reserved label and a specific meaning in the API Gateway policy framework:
Role
Label
Description
Global
Request
Policy
system.policy.request
Executed globally for all messages passing through the API Gateway on the request path.
Global
Response
Policy
system.policy.response
Executed globally for all messages passing through the API Gateway on the response path.
Global
Fault
Handler
Policy
system.policy.faulthandler
If any policy aborts during execution, or a top-level policy fails and has not specified a Fault Handler filter, this policy is executed instead of the internal SOAP Fault filter.
You can select specific policies with these roles under the Policies node in the Policy Studio tree. You can then create links to these roles when creating a Policy Shortcut Chain. These steps are explained in the next sections.
Axway API Gateway 7.5.2
Policy Developer Guide 77
2 Manage policies
Select a global policy
To select a global policy, right-click a policy under the Policies node, and select one or more global policies (for example, Set as Global Request Policy, Set as Global Response Policy, or Set
as Global Fault Handler Policy). These policies are executed globally for all messages passing through API Gateway. The following example shows the XML Threat Policy set as the Global Request Policy. The policy node labeled for the specific role is displayed with a globe icon:
When you have selected the policy for a specific role, you can then reference the labeled policy in a Policy Shortcut Chain filter, or at the service level in a relative path or web service resolver. Referencing a labeled policy is different from referencing a specific policy directly. Referencing a policy directly involves selecting a specific policy to execute in the chain. Referencing a labeled policy means selecting a filter by its label only.
The main advantage of this approach is that you can configure a policy to run in a policy shortcut chain in a specific role, and then select a different policy as the global policy for that role. All references to the global policy label in the various shortcut chain filters are changed to use the newly selected policy, without requiring you to modify each policy shortcut chain filter individually to explicitly point to a different policy. Selecting another policy in a global role deselects the previously selected policy. The following example shows the Health Check set in the global role, and the XML Threat Policy is no longer selected:
Axway API Gateway 7.5.2
Policy Developer Guide 78
2 Manage policies
Note
You cannot select a policy for a specific role if, in doing so, you create a loop in the policies. For example, if a Policy Shortcut Chain filter has a reference to a labeled policy, and the filter’s parent policy is marked as the labeled policy, the filter would call back to itself in a loop. This error is caught, and a trace line is output to Policy Studio Console view.
Configure global policies in a policy shortcut
chain
When adding a policy shortcut in a Policy Shortcut Chain filter, you can select to call a labeled policy instead of selecting a specific policy. The following example from the Add a new Shortcut
to a Policy dialog shows adding a shortcut to the Global Request Policy (Health Check) policy label:
Then if you select a different policy as the request policy in the Policy Studio tree, when you subsequently view this shortcut in the chain filter, you see that the details for the shortcut have changed. The following example from the Edit the Shortcut to the Policy dialog shows the policy label changed to Global Request Policy (XML Threat Policy).
Axway API Gateway 7.5.2
Policy Developer Guide 79
2 Manage policies
For more details on configuring these windows, see Policy shortcut chain on page 832.
Note
If you remove a label from a policy by deselecting it in the Policy Studio tree, any reference to that labeled policy is not called when evaluating the shortcut in the chain, irrespective of whether Evaluate this shortcut when executing the chain is selected (the Active status column in the table view). This corresponds with the behavior for a specific policy in the chain. If a link to a policy is not set for a shortcut, the link is not evaluated.
In this example, the table shows that the shortcut is configured to point to the labeled policy, but the label does not resolve to a policy (for example, it is unspecified because there is no policy in the specified role):
Configure global policies for a service
Under the Environment Configuration > Listeners node, you can also configure global policies at the service level to run on a specific relative path or web service resolver when messages are received by API Gateway. A relative path binds a policy to a specific relative path location (for example /healthcheck). A web service resolver maps messages destined for a specific web service to a Service Handler or Web Service Filter. You can configure a global policy at the service level to run as part of a policy chain invoked when incoming messages are received by API Gateway. The following example shows the Global
Request Policy configured to run first on the /healthcheck relative path:
For more details, see Configure relative paths on page 308.
Axway API Gateway 7.5.2
Policy Developer Guide 80
2 Manage policies
Show global policies
To view the currently configured global policies, right-click the Policies root tree node, and select Show Global Policies. This displays all currently configured global policies in the context menu, for example:
Note
If there are no global policies configured, the S how Global Policies menu item is not available.
Configure policy assemblies
Overview
In certain cases, you might need to convert a policy into a modular reusable piece of functionality that can be called from other policies. For example, you have a complex policy that creates a WS-Security UsernameToken, inserts it into the message, and subsequently creates an XML Signature over the token and SOAP body. Depending on the message recipient, the content might need to be signed using slightly different settings. One service might require a <sp:Basic128/> algorithm suite, while another might require <sp:Basic256/>).
Similarly, subtle differences in security requirements might require the token and signature to be generated differently. For example:
l Use a basic or digest password for the UsernameToken
l Insert a <dsig:CarriedKeyName> into the XML-Signature
l Create an enveloped or enveloping signature
l Include a <wsse:BinarySecurityToken>
l Use one signing key over another
l Sign different parts of the message
If you need to create separate policies for such cases, interoperating with different vendor services can become arduous. This involves creating several complicated policies that might only differ in one field in each filter. To avoid this duplication, you can create a policy assembly that inserts the WS-Security UsernameToken into the message and generates the XML-Signature. Axway API Gateway 7.5.2
Policy Developer Guide 81
2 Manage policies
However, instead of explicitly configuring fields mentioned above (for example, enveloped or enveloping signature, include a <wsse:BinarySecurityToken>, or signing key to use), the policy assembly can use selectors for these fields, which are configured dynamically at runtime. For more details, see Select configuration values at runtime on page 854.
The policy assembly advertises that it requires configuration details to be called generically from other policies. For example, it requires the key to sign the message. By templating the signing policy as a policy assembly, and making it available to call from other policies like any other filter, the caller must set the signing key for the policy assembly. In this way, different policies that require a signed UsernameToken can call the same policy assembly. By using selectors to pass in different signing keys, messages are signed using the appropriate key for each calling policy.
When a policy has been configured as a policy assembly, it is displayed in the Policy Studio filter palette, and you can drag and drop it into any policy that requires the functionality in the assembly. You must configure any fields required by the policy assembly when it is dragged and dropped on to the canvas of another policy.
Configure a policy assembly
To configure a policy as a policy assembly in Policy Studio, perform the following steps:
1. Right-click the policy in the tree on the left, and select Policy Assembly > Create.
2. Specify the following settings on the General tab:
l Palette Category:
Enter the filter palette category in which to display the policy assembly (for example, Monitoring). l Palette Icon:
Enter the path to the palette icon to display for the policy assembly (for example, C:\Axway\apigateway\icons\monitor.ico). 3. The Input tab lists all required message attributes for the policy assembly. You can enter userfriendly names for each attribute to be displayed in the Policy Activation filter for the policy assembly (for example, HTTP Headers for the http.headers attribute).
4. The Output tab lists the generated message attributes for the policy assembly. To add a generated attribute, click Add, and enter the following details:
l Expression:
Enter the selector expression for the attribute (for example, ${content.body}). l Attribute Type:
Enter the message attribute type (for example, com.vordel.mime.Body). l Output Attribute Name:
Enter the message attribute generated by the policy assembly (for example, content.body). 5. When finished, click OK.
Axway API Gateway 7.5.2
Policy Developer Guide 82
2 Manage policies
6. Click the Deploy button in the toolbar to deploy the newly created policy assembly to API Gateway.
Apply a policy assembly
When a policy is configured as a policy assembly, it is available for reuse in the Policy Studio filter palette. Dragging and dropping the policy assembly on to the policy canvas displays the Policy
Activation Filter window for that policy assembly. This enables you to specify any required message attributes and filter-level monitoring settings.
Specify required attributes
The Required Attributes tab enables you to set the configuration fields required by the policy assembly (for example, those configured with selectors for dynamic configuration). Click Add to specify the following fields:
l Required Attribute:
Enter the name of the required attribute for display (for example, HTTP Header). l Raw Attribute Name:
Enter the message attribute name (for example, http.headers). l Attribute Type:
Enter the message attribute type (for example, com.vordel.mime.HeaderSet). l Value/Selector:
Enter a message attribute value or selector (for example, ${http.headers}). Specify monitoring settings
The Traffic Monitor tab enables you to set the following filter-level monitoring settings:
l Record outbound transactions:
Select whether to record outbound message transactions sent from API Gateway to remote hosts. This is enabled by default. l Record policy path:
Select whether to record the policy path for the message transaction, which shows the filters that the message passes through. This is enabled by default. Axway API Gateway 7.5.2
Policy Developer Guide 83
Web services
3
This section describes how to register and secure web services.
Register and secure web services
84
Configure policies from WSDL files
86
Manage web services
101
Manage WSDL and XML schema documents
107
Manage JSON schemas
116
Manage data maps
117
Expose a web service as a REST API
123
Develop REST APIs in Policy Studio
131
Connect to a UDDI registry
139
Retrieve WSDL files from a UDDI registry
143
Publish WSDL files to a UDDI registry
154
Register and secure web services
Overview
Policy Studio provides the following features that enable you to register and secure web services:
l You can register a web service in Policy Studio by importing a WSDL file into the web service repository. For more information on registering web services, see Manage web services on page 101.
l The Import WSDL wizard enables you to automatically generate the policies to protect web services. For more information on using the wizard, see Configure policies from WSDL files on page 86.
l You can also manually configure policies to protect web services (for example, if a WSDL file is not available). For more information, see Configure policies manually on page 74.
l You can also invoke registered web services from policies, for example, when you expose a SOAP web service as a REST API, the REST API you define calls a policy to implement the API, which in turn invokes the SOAP web service. For more information, see Expose a web service as a REST API on page 123.
Axway API Gateway 7.5.2
Policy Developer Guide 84
3 Web services
WSDL and XML schema cache
API Gateway maintains a global cache of WSDL and XML schema documents. For more information on adding, updating, and deleting WSDL and XML schema documents, see Manage WSDL and XML schema documents on page 107.
API Gateway validates XML schemas and WSDL documents during import. For more information, see XML schema and WSDL document validation on page 113. To test a WSDL for WS-I compliance, see Test a WSDL for WS-I compliance on page 115.
JSON schema cache
API Gateway maintains a global cache of JSON schemas. For more information, see Manage JSON schemas on page 116.
WSDLs from a UDDI registry
WSDL documents can be imported from and published to a Universal Description, Discovery, and Integration (UDDI) registry. For more information, see the following topics:
l Connect to a UDDI registry on page 139
l Retrieve WSDL files from a UDDI registry on page 143
l Publish WSDL files to a UDDI registry on page 154
Data maps
You can create data maps to map XML and JSON messages to other XML and JSON message formats using a graphical editor. For more information, see Manage data maps on page 117.
Policy Studio filters
The following Policy Studio filters are of interest when working with web services:
l The Web Service filter is the main filter generated when a WSDL file is imported into the web service repository. It contains all the routing information and links all the policies that are to be run on the request and response messages into a logical flow. For more information, see Web service filter on page 845.
l The Schema Validation filter is used to validate XML messages against XML schemas stored in the global cache. For more information, see Schema validation on page 605.
l The JSON Schema Validation filter is used to validate JSON messages against JSON schemas stored in the global cache. For more information, see JSON schema validation on page 597.
Axway API Gateway 7.5.2
Policy Developer Guide 85
3 Web services
l You can use the Execute Data Map filter to execute a mapping you defined in a data map as part of a policy. For more information, see Transform with data map on page 643.
Configure policies from WSDL files
Overview
When you import a WSDL file describing a web service into the web service repository, API Gateway exposes a virtualized version of the web service. This virtualized service is exposed on a host and port of the machine running API Gateway (for more information on how this is achieved see Publish the WSDL on page 106). In this way, a client can retrieve the WSDL for the virtualized web service from API Gateway without knowing its real location.
When you import a WSDL file, Policy Studio automatically generates policies that can be used to talk to the back-end web service. For example, a Service Handler is created to resolve and validate requests to the web service and responses from the web service. The service handler is automatically configured based on the operation definitions in the WSDL. A WSDL file can include WS-Policy assertions that define the security policies or security requirements that a client must adhere to in order to communicate with the corresponding service. For example, a web service might require the client to sign sensitive parts of the message and include a WS-Security UsernameToken to authenticate to the web service. If the imported WSDL file contains WS-Policy assertions, API Gateway is responsible for making sure the requests it sends to the web service adhere to the security constraints specified in the policy. In this case API Gateway is considered as the initiator o f the web service.
During the WSDL import process, you can select which operations to expose to clients and what path to expose the service on, and you can also specify the WS-Policy assertions that API Gateway enforces on the messages it receives from clients. In this case, API Gateway is considered to be the recipient to a consumer (that is, client) of the virtualized web service.
You can use the Import WSDL wizard to configure API Gateway as a web service initiator, as a recipient to a consumer of the virtualized web service, or both. The steps involved in the wizard, and the configuration windows displayed, differ according to whether WS-Policy assertions are being enforced between API Gateway and the web service (initiator case) or between a client and API Gateway (recipient case). For more information on the Import WSDL wizard, see Import a WSDL file on page 88.
The Import WSDL wizard enables you to configure complex policies to secure and virtualize web services with only a few clicks and minimal intervention. API Gateway as the web service initiator
The following figure demonstrates the case where API Gateway is the initiator of the web service:
Axway API Gateway 7.5.2
Policy Developer Guide 86
3 Web services
When the imported WSDL describing the web service includes WS-Policy assertions, API Gateway is responsible for making sure that the requests it sends to the web service adhere to the security constraints specified in the policy.
Policy Studio automatically generates the policies required to talk to the web service, and to enforce the security requirements specified by the policy assertions in the WSDL. These policies contain filters, most of which are configured automatically. However, a small number of filters require you to manually configure specific fields. For example, when signing or encrypting a message, you must specify the signing or encrypting key. API Gateway as the web service recipient
The following figure demonstrates the case where API Gateway is the recipient of the web service:
When importing the WSDL, the Import WSDL wizard enables you to select the web service operations to expose to the client, set the path on which to expose the service, and optionally to specify the security policies that API Gateway enforces on the messages it receives from the client. Policy Studio automatically generates the policies that API Gateway uses to talk to the client, and to enforce the security requirements you specified during WSDL import. These policies contain filters, Axway API Gateway 7.5.2
Policy Developer Guide 87
3 Web services
most of which are configured automatically. However, a small number of filters require you to manually configure specific fields. For example, when configuring the duration of a WS-Security timestamp, you might need to specify a longer or shorter duration. Import WSDL summary
The steps involved in the Import WSDL wizard are summarized as follows:
1. Load the WSDL from a file, URL, or UDDI.
2. Retrieve and validate the WSDL.
3. Select the operations to expose.
4. Configure the WS-Policy settings. If the imported WSDL file includes WS-Policy settings, policies are generated to secure the connection between API Gateway and the web service. You can also secure the virtualized service by configuring WS-Policy settings between the client and API Gateway at this step.
5. Select the path to expose the services on.
6. If you selected to secure the virtualized service using WS-Policy settings, configure the policies that API Gateway needs to enforce for messages it receives. You can select gateway and message level policies at this step.
7. Configure the recipient security settings. At this step you can manually configure the policies that have been automatically generated by Policy Studio to enforce the WS-Policy settings between the client and API Gateway.
8. Configure initiator security settings. At this step you can manually configure the policies that have been automatically generated by Policy Studio to enforce the WS-Policy settings between API Gateway and the back-end web service.
9. Review the summary information for the virtualized service. At this step you can also override the default validation and routing policies with custom policies, and decide whether or not to publish the WSDL to clients.
Import a WSDL file
To import a WSDL file into the web service repository, complete the following steps:
1. In the Policy Studio tree view, expand the APIs > Web Service Repository node.
2. Right-click the Web Services node, and select Register Web Service to launch the Import
WSDL wizard.
3. In the Load WSDL window, select the WSDL location from one of the following options:
l WSDL File:
Click the Browse button to select a WSDL file from the file system.
Axway API Gateway 7.5.2
Policy Developer Guide 88
3 Web services
l WSDL URL:
Enter a URL where the WSDL can be loaded from. This option supports HTTP basic authentication. Under Authentication select the Use HTTP Basic option and enter a user name and password.
l WSDL from UDDI:
Click the Browse UDDI button to select a WSDL file from a Universal Description, Discovery, and Integration (UDDI) registry. For more information on how to retrieve a WSDL file from a UDDI registry, see Retrieve WSDL files from a UDDI registry on page 143.
Click Next.
4. In the Retrieve and Validate window, enter a user name and a comment for this version of the WSDL. Click Next to continue.
Note
If the WSDL fails validation, an error is displayed. For more information, see XML schema and WSDL document validation on page 113 and XML schema and WSDL document limitations on page 113.
5. In the WSDL Operations window, select the operations to be exposed on the virtualized service and click Next. Alternatively, click Select All or Select None to select all or none of the operations defined in the WSDL file.
6. On the WS-Policy Options window, select Secure this virtualized service with a WSPolicy to use a WS-Policy to secure the virtualized service. If you select this option, the Secure
Virtual Service dialog is displayed at a later step, which enables you to configure WS-Policy settings between the client and API Gateway and generate policies that API Gateway uses to enforce for messages it receives from clients. 7. On the WS-Policy Options window, select Use the WS-Policy in the WSDL to connect
securely to the back-end Web Service to generate policies to secure the connection between API Gateway and the web service, based on the WS-Policy settings included in the WSDL file. This is enabled (and selected by default) only if the imported WSDL file includes WSPolicy information. Click Next to continue.
8. On the Expose Services window, select or enter a unique relative path on which to expose the virtualized service (for example, Default Services). Note
If the WSDL file contains multiple services, you must select a relative path for each service before continuing. Select a service from the Select a service field, and then select or enter a unique relative path to expose that service on. Repeat for each service.
9. Click Finish. The configuration is prepared based on your selections and one or more of the following windows are then displayed:
l Secure Virtual Service
If you selected to secure the virtualized service with a WS-Policy, this window is displayed. For more information, see Configure a security policy on page 90.
l Configure Recipient Security Settings
This window is displayed if you selected to secure the virtualized service with a recipient WS-Policy. For more information, see Configure recipient security settings on page 91.
Axway API Gateway 7.5.2
Policy Developer Guide 89
3 Web services
l Configure Initiator Security Settings
This window is displayed if selected to use the WS-Policy in the WSDL to secure messages sent from API Gateway (as initiator) to the web service. For more information, see Configure initiator security settings on page 91.
10. After you have completed configuring the security settings, the Summary window is displayed. This window summarizes the details for the imported WSDL file. It includes the location of the WSDL file, and a tab for each web service virtualized by API Gateway. Each tab includes the following: l The name of the virtualized service.
l The path that the WSDL for the virtualized service is exposed on.
l Validation:
API Gateway uses the WSDL to validate incoming messages by default. Alternatively, you can select the check box and click the browse button to use a dedicated validation policy for all messages sent to the web service. For example, this enables you to delegate to a custom validation policy used by multiple web services. l Routing:
API Gateway routes to the displayed URL by default. Alternatively, you can select the check box and click the browse button to use a dedicated routing policy to send all messages on to the web service. For example, this enables you to delegate to a custom routing policy used by multiple web services. l WSDL Access Options:
Select the Allow the Gateway to publish WSDL to clients option to make the WSDL for this web service available to clients. This option is selected by default. The published WSDL represents a virtualized view of the web service. Clients can retrieve the WSDL from API Gateway, generate SOAP requests, and send them to API Gateway, which routes them on to the web service. For more details, see Publish the WSDL on page 106. These options enable you to configure the underlying auto-generated Service Handler without having to navigate to it in the Policies tree. Review the information on each tab and click OK to close the wizard.
Configure a security policy
The Secure Virtual Service dialog enables you to specify the policy that API Gateway enforces on the messages that it receives from the client. To specify a policy, perform the following steps:
1. Select a policy from the Gateway Policy field. A description for the currently selected policy is displayed in the dialog. For details on all the available policies, see WS-Policy reference on page 881.
Axway API Gateway 7.5.2
Policy Developer Guide 90
3 Web services
2. Select a message-level request policy from the Request Policy field. The available policies are as follows:
l Encrypt SOAP Body
l Sign SOAP Body
l Sign and Encrypt SOAP Body
3. Select a message-level response policy from the Response Policy field. The available policies are the same as for Request Policy.
4. Click OK.
Configure recipient security settings
If API Gateway is configured as a recipient for the client, the Configure Recipient Security
Settings window is displayed. This window enables you to configure the filters used to implement the rules required by the WS-Policy settings you selected in the Secure Virtual Service window. The exact sequence of filters differs depending on the policies that you selected. For example, if a policy with a SAML token is selected, the Validate SAML Authentication
Assertion filter is displayed, whereas if a WS-Policy requiring a WS-Security UsernameToken is selected, the Validate WS-Security Username Token filter is displayed. The effort required to configure these filters is minimal because most of the fields are populated automatically from the WS-Policy assertions. For example, the layout, signing, encryption, and key wrapping algorithms, key referencing method, user name digest, and clear password are all automatically populated from the WS-Policy assertions. This means that you only need to configure a small number of settings, such as the signing key, encryption certificate, and timestamp validity period. Configure initiator security settings
If API Gateway is configured as an initiator of the web service, the Configure Initiator Security
Settings window is displayed. This window enables you to configure the filters used to implement the rules required by the WS-Policy settings specified in the imported WSDL file. The exact sequence of filters differs depending on the WS-Policy assertions contained in the WSDL. For example, if an sp:SamlToken assertion is specified, the wizard contains a window for the Insert SAML Authentication Assertion filter. The effort required to configure these filters is minimal because most of the fields are populated automatically from the WS-Policy assertions in the WSDL.
In the case of the Sign Message filter, the decision to use asymmetric or symmetric signatures is based on whether the policy uses an asymmetric or symmetric binding. The layout rules are determined by the sp:Layout assertion. The digest method, signature method, and key wrap algorithm (for symmetric signatures) are all populated automatically based on the contents of the sp:AlgorithmSuite assertion. The KeyInfo section of the XML Signature can be taken from various properties set in the WSDL. The parts of the message to be signed can be inferred from assertions such as sp:SignedParts, sp:SignedElements, and SignedSupportingTokens. Axway API Gateway 7.5.2
Policy Developer Guide 91
3 Web services
The same is true for the XML Encryption Settings filter where the encryption algorithms and key types can all be taken from the assertions in the WSDL. The ConfirmationMethod for SAML assertions can be inferred from the context of the SamlToken assertion. For example, an sp:SamlToken that appears as a child of the sp:SignedSupportingTokens assertion uses a sender-vouches confirmation method, whereas if it appears as a child of an sp:EndorsingSupportingTokens assertion, the holder-of-key confirmation method can be assumed.
Configure recipient policy filters
The following tables describe the filters that can be created when API Gateway is configured as a recipient. You can configure these filters in the Configure Recipient Security Settings window. For simplicity, only filters that require manual input are shown, and only the fields that might require manual input are detailed in the tables. Insert Timestamp Filter
Field
Name
Description
Expires
In
You can specify a more appropriate lifetime for the assertion (instead of the default one hour) by configuring the various time period fields.
Signed Parts Outbound Filter
Field
Name
Description
Signing
Key
If the policy uses an asymmetric binding, on the Asymmetric tab, click the Signing Key button, and select a key from the certificate store to sign the message parts with. Alternatively, if the policy specifies a symmetric binding, on the Symmetric tab, click the Signing Key button, and select a key to wrap the symmetric signing key with.
Axway API Gateway 7.5.2
Policy Developer Guide 92
3 Web services
Find Recipient Certificate for Encryption
Field
Name
Description
Certificate
Store
Click the Select button to choose the recipient's certificate from the certificate store. The public key contained in this certificate is used to encrypt the message parts so that only the recipient is able to decrypt them using the corresponding private key.
Validate SAML Authentication Assertion
Field
Name
Description
Drift
Time
You can specify a drift time value to allow for a time differential between the clock on the machine hosting API Gateway and the machine hosting the web service.
Trusted
Issuers
On the Trusted Issuers tab, click Add to specify the Distinguished Name of a SAML authority whose certificate has been added to the certificate store, and click OK. Repeat this step to add more SAML authorities to the list of trusted issuers.
Configure SSL Certificate
Field Name
Description
X.509
Certificate
On the Network tab, click the X.509 Certificate button to create or import an SSL certificate.
SSL Server
Name
Identifier
(SNI)
On the Network tab, click the Add button to configure a server name in the SSL Server Name Identifier (SNI) dialog. You can specify the server name in the Client requests server name field. Click the Server
assumes identity button to import a certificate authority certificate into the certificate store. Mutual
Authentication
On the Mutual Authentication tab, select root certificate authorities trusted for mutual authentication.
Axway API Gateway 7.5.2
Policy Developer Guide 93
3 Web services
Insert MTOM Content
Field
Name
Description
XPath
Location
When the wsoma:OptimizedMimeSerialization WS-MTOM Policy assertion is specified in a recipient policy, you must configure an Insert MTOM
Content filter. Configure an XPath expression that points to the base64-encoded element content to insert and create an MTOM type attachment for.
Configure initiator policy filters
The following tables describe the filters that can be created when API Gateway is configured as an initiator. You can configure these filters in the Configure Initiator Security Settings window. For simplicity, only filters that require manual input are shown, and only the fields that might require manual input are detailed in the tables. Insert WS-Security Timestamp
Field
Name
Description
Expires
In
You can specify a more appropriate lifetime for the assertion (instead of the default one hour) by configuring the various time period fields.
Sign Message
Field
Name
Description
Signing
Key
If the policy uses an asymmetric binding, on the Asymmetric tab, click the Signing Key button, and select a key from the certificate store to sign the message parts with. Alternatively, if the policy specifies a symmetric binding, on the Symmetric tab, click the Signing Key button, and select a key to wrap the symmetric signing key with.
Axway API Gateway 7.5.2
Policy Developer Guide 94
3 Web services
Insert WS-Security Username
Field
Name
Description
Username
Enter the user name inserted into the WS-SecurityUsernameToken block. By default, the name of the authenticated user is used, which is stored in the authentication.subject.id message attribute. However, you can enter any value in this field.
Password
If the policy requires a password, the password for the user entered above must be specified here. You can use the default authenticated user password by selecting the authentication.subject.password message attribute. Alternatively, you can enter any suitable password. The decision to use a Clear or Digest password is taken from the corresponding policy assertions.
Insert SAML Authentication Assertion
Field
Name
Description
Expire
Specify a suitable lifetime for the SAML assertion by configuring the various time In
period fields.
Drift
Time
You can specify a drift time value to allow for a time differential between the clock on the machine hosting API Gateway and the machine hosting the web service.
Issuer
Name
Select the alias of the certificate from the certificate store to use to identify the issuer of the assertion. The alias name is used as the value of the Issuer attribute of the saml:Assertion element.
Holder
of Key:
Signing
Key
In cases where the sp:SamlToken appears as a child ofEndorsingSupportingTokens or an InitiatorToken, the holder-
of-key SAML confirmation method is inferred. In this case, if an asymmetric binding is used, on the Asymmetric tab, specify a key from the certificate store by clicking the Signing Key button. Alternatively, if a symmetric binding is used in the policy, on the Symmetric tab, specify a key to use to encrypt the symmetric key with by clicking the Signing Key button. Axway API Gateway 7.5.2
Policy Developer Guide 95
3 Web services
Find Recipient Certificate for Encryption
Field
Name
Description
Certificate
Store
Select this option, and click the Select button to choose the recipient's certificate from the certificate store. The public key contained in this certificate is used to encrypt the message parts so that only the recipient is able to decrypt them using the corresponding private key.
Connect to URL
Field Name
Description
Trusted
Certificates
To connect to an external web service over SSL, you need to trust that web service's SSL certificate. You can do this on the Trusted Certificates tab of the Connect to URL filter. Assuming you have already imported this certificate into the trusted certificate store, simply select it from the list.
Client SSL
Authentication
If the web service requires the client to present an SSL certificate to it during the SSL handshake, you must select that certificate from the list on the Client SSL Authentication tab. Note
This certificate must have a private key associated with it that is also stored in the certificate store.
Extract MTOM Content
Field
Name
Description
XPath
Location
When the wsoma:OptimizedMimeSerialization WS-MTOM Policy assertion is specified in an initiator policy, you must configure an Extract MTOM
Content filter. Configure an XPath expression that points to the base64-encoded element content to extract and create an MTOM type attachment for.
Edit the recipient or initiator WS-Policy
To edit a previously configured WS-Policy (for example, to change the signing key in the autogenerated policy), right-click the web service in the Policy Studio tree, and select WS-Policy >
Edit Recipient WS-Policy or WS-Policy > Edit Initiator WS-Policy. You can also add or Axway API Gateway 7.5.2
Policy Developer Guide 96
3 Web services
remove a recipient WS-Policy after import by selecting the WS-Policy > Add Recipient WSPolicy or WS-Policy > Remove Recipient WS-Policy options. These options are described as follows:
Edit Recipient WS-Policy
If you configured a recipient WS-Policy during WSDL import (using the Secure Virtual Service window), you can edit its filters using this option. If you did not configure a recipient WS-Policy during WSDL import, this option is disabled. Add Recipient WS-Policy
If you did not configure a recipient WS-Policy during WSDL import (using the Secure Virtual
Service window), this option enables you to add a recipient WS-Policy after import. The Secure
Virtual Service window is displayed when you select this option followed by the Configure
Recipient Security Settings window. This enables you to select and configure a WS-Policy to enforce between the client and API Gateway. Remove Recipient WS-Policy
If you configured a recipient WS-Policy during WSDL import (using the Secure Virtual Service window), you can remove it using this option. If you did not configure a recipient WS-Policy during WSDL import, this option is disabled. Edit Initiator WS-Policy
If the imported WSDL file included WS-Policy assertions, you can edit the filters used to implement the WS-Policy assertions in the WSDL using this option. However, if there was no WS-Policy in the imported WSDL file, you cannot use this option. You cannot add an initiator WS-Policy after WSDL import because that would break the contract between API Gateway and the back-end web service. If the contract for the web service changes (for example, a WS-Policy is applied to it at the back-end), you can reimport the WSDL.
Configure a recipient WCF WS-Policy
API Gateway provides four WS-Policies that are identical to those exposed by WCF (Windows Communication Foundation) web services. When one of these policies is exposed by a virtual service in API Gateway, the svcutil .NET web services utility can consume the WS-Policy and auto-generate clients that communicate securely with API Gateway.
The security settings for a WCF web service are configured in its web.config file, in which the security element determines the WS-Policy applied to the service. For example, the following extract from a WCF web service web.config file shows the configuration:
<customBinding>
<binding name="MyCustomBinding">
<textMessageEncoding messageVersion="Soap11" />
<security defaultAlgorithmSuite="Basic256"
allowSerializedSigningTokenOnReply="true"
authenticationMode="MutualCertificate" requireDerivedKeys="false"
includeTimestamp="true"
messageProtectionOrder="SignBeforeEncrypt"
Axway API Gateway 7.5.2
Policy Developer Guide 97
3 Web services
messageSecurityVersion="WSSecurity10..."
requireSecurityContextCancellation="false">
</security>
</binding>
</customBinding>
In this example, the authenticationMode for a customBinding is set to MutualCertificate, which means that messages sent to and from the web service must be signed and encrypted with mutual certificates. The following example shows an example of the WCF wsHttpBinding configuration, which is less verbose:
<wsHttpBinding>
<binding name="MyWsHttpBinding">
<security mode="Message">
<message clientCredentialType="Certificate" />
</security>
</binding>
</wsHttpBinding>
The following table shows how the WCF WS-policies provided with API Gateway correspond to a particular configuration of the security element in the WCF web service web.config file. As shown in the preceding examples, the configuration settings are slightly different, depending on the WCF binding ( customBinding or wsHttpBinding). The following table shows the available settings:
WS-Policy Name
WCF
Binding
Authentication Mode
Securi
ty
Mode
Client
Credential
Type
WCF
MutualCertificate
Service
customBin
MutualCertificat
—
—
ding
e
WCF
UsernameForCertifica
te Service
customBin
UserNameForCerti
—
—
ding
ficate
WCF
UsernameOverTransp
ort Service
customBin
UsernameForTrans
—
—
ding
port
WCF
BrokeredX509Authen
tication Service
wsHttpBin
—
Mess
Certific
age
ate
Note
ding
If you intend to consume the WS-Policy exposed by API Gateway with a WCF client, you should use one of the WCF WS-Policies. All of these policies can be consumed seamlessly by the WCF svcutil utility to auto-generate secure clients. While the other WS-Policies Axway API Gateway 7.5.2
Policy Developer Guide 98
3 Web services
exposed by API Gateway can be consumed by svcutil, you need to make additional configuration changes to the auto-generated WCF client to communicate securely with API Gateway. For more details on making any necessary configuration changes, see your WCF documentation. Remove security tokens
When you import a WSDL file containing a WS-Policy into the web service repository, the Remove
All Security Tokens filter is enabled in the Service Handler for the imported web service. To view the configured policy, double-click the Service Handler, and select the Message
Interception Points > 2. User-defined Request Hooks tab. The Remove All Security Tokens policy ensures that the following security contexts are kept separate:
l Recipient security context: This is between the client and API Gateway, and is determined by the WS-Policy selected in the Secure Virtual Service window. l Initiator security context: This is between API Gateway and the back-end web service, and is determined by the WS-Policy contained in the imported WSDL file for the back-end web service.
The Remove All Security Tokens policy prevents tokens from one context passing over into the other context, which could breach the security contract governing that context. This ensures that each security context receives a clean SOAP message, on which it can then act to enforce the security requirements of the relevant WS-Policy. The following diagram shows both security contexts and the Remove All Security Tokens policy:
Recipient-side WS-Policy only
In this case, a recipient WS-Policy is configured in the Secure Virtual Service window to protect a virtual service exposed by API Gateway. The recipient WS-Policy defines the security contract between the client and API Gateway. Any security tokens sent by the client are intended for consumption by API Gateway. They are not intended for the back-end web service. Axway API Gateway 7.5.2
Policy Developer Guide 99
3 Web services
For example, the web service might not understand SAML, WS-Security, XML Signature, and so on, which might result in a serialization error if these tokens are propagated to it. In addition, it would add unnecessary overhead to the message to propagate security tokens to it. On the response side, the response that API Gateway returns to the client must adhere to the selected recipient WS-Policy. For example, if the web service has returned a SAML token (out of scope of any WS-Policy requirements), this must not be returned to the client because it would breach the recipient WSPolicy.
Initiator-side WS-Policy only
In this case, the WS-Policy is contained in the imported WSDL file. The WS-Policy defines the security contract between API Gateway and the back-end web service defined in the WSDL. On the request side, any security tokens sent by the client to API Gateway, which are out of scope of the initiator WS-Policy between API Gateway and web service, are removed before API Gateway starts enforcing the initiator WS-Policy on the request, and before it sends the request to the web service.
For example, if the client sends a wsu:Timestamp in the request message and the initiator policy stipulates that a wsu:Timestamp must be sent by API Gateway to the web service, two timestamps could be sent in the request, which is invalid. This means that the timestamp and any other security tokens sent by the client to API Gateway, which might contradict the rules in the initiator contract (between API Gateway and the web service) must be stripped out before API Gateway starts adding security tokens to the message. This ensures that the message adheres to the initiator WS-Policy.
Similarly, any security tokens returned by the web service are only present because the web service complies with the contract between the web service and API Gateway. Therefore, any tokens returned by the web service are only intended for use by API Gateway. They are not intended for consumption by the client. In other words, the security context is only between API Gateway and the web service. If the web service returns a UsernameToken, it is consumed by API Gateway. If a token must be returned to the client, this is a user-enforced rule, which is out of scope of the WS-Policy configuration in the WSDL. If necessary, you can override the default behavior by removing the Remove All Security Tokens filter from the Service Handler to allow the UsernameToken to be propagated to the client. Initiator-side and Recipient-side WS-Policy
This occurs when you import a WSDL file that includes a WS-Policy (initiator case), and you also select a WS-Policy in the Secure Virtual Service window (recipient case). This scenario includes both the recipient security context b etween the client and API Gateway, and the initiator security context b etween API Gateway and the web service.
It is vital that these security contexts are kept separate because if tokens from one context pass over into the other context, it is highly likely that the security contract for that context will be breached. For example, if the recipient contract between the client and API Gateway requires a UsernameToken, but the initiator contract between API Gateway and the web service requires a SAML token, the UsernameToken must not pass over into the initiator context and be sent to the web service. Note
The Remove All Security Tokens policy only applies when a WS-Policy is configured, and is not enabled when a WS-Policy is not configured. In addition, any non-standard Axway API Gateway 7.5.2
Policy Developer Guide 100
3 Web services
behavior that requires a security token to be propagated over to another security context can be handled by disabling the Remove All Security Tokens policy in the Service
Handler for the imported WSDL. Manage web services
Overview
The Web Service Repository stores information about web services whose definitions have been imported using Policy Studio. The WSDL files that contain these web services definitions are stored together with their related XML schemas. Clients of the web service can then query the repository for the WSDL file, which they can use to build and send messages to the web service using API Gateway. The web service repository enables you to register web services by importing a WSDL file, and to group related web services into groups. When you register a web service in the web service repository, Policy Studio auto-generates a Service Handler that is used to control and validate requests to the web service and responses from the web service. If a web service is updated after initial import, you can resynchronize with it to import new versions of the WSDL and XML schemas, and the Service Handler is regenerated to reflect the updates. This topic describes how to manage web services and groups, and explains what happens when you import a WSDL file to register a web service. This topic also describes how to export a registered web service, how to update (or resynchronize) an existing web service, and how to expose additional operations on a web service.
Manage web services and groups
The Web Service Repository is displayed under the APIs node in the Policy Studio tree. WSDL files are imported into web service groups, which provide a convenient way of keeping groups of related web service definitions together. To import a WSDL file into the default group, right-click the Web Services node, and select Register Web Service. Alternatively, to add a new web service group, right-click the default Web Services group, or the Web Service Repository node, and select Add a new web services group. When the new group is added, you can right-click it in the tree, and select Register Web Service.
Register a web service
Registering a web service involves importing the WSDL file that contains the definitions for the web service. Policy Studio provides an Import WSDL wizard to make registering a web service a simple process that requires minimal manual intervention. For more information on registering a web service by importing a WSDL file, see Configure policies from WSDL files on page 86.
Axway API Gateway 7.5.2
Policy Developer Guide 101
3 Web services
The Import WSDL wizard auto-generates policies and service handlers for each web service imported. These are automatically configured wherever possible, based on the imported WSDL. This means that only a small number of fields need to be configured manually. After a web service has been registered using the Import WSDL wizard, the WSDL for the service is published b y API Gateway. Clients can specify WSDL on a request query string to retrieve the WSDL file (for example, http://localhost:8080/HelloWorldService/HelloWorld?WSDL). For more details, see Publish the WSDL on page 106. Tip
You can also register a web service using a script. For more information, see Use scripts to manage web services on page 106.
Results of registering a web service
Service handlers and policies are auto-generated when you register a web service by importing a WSDL file in Policy Studio. The specific policies that are created depends on whether you configured a policy to enforce security between the client and API Gateway, and whether the imported WSDL file contained any WS-Policy assertions. The following list summarizes what is created by the wizard:
Web service
A new web service tree node is created in the Web Service Repository tree for each web service that you selected to expose operations from in the imported WSDL. The web service is created in the Web Services group by default. Click the new web service node to list the WSDL file for the service and any imported WSDL files and XML schemas. To view the source for a WSDL or XML schema file, click the file and a read-only view of the source is displayed. Note
It is important to realize that the WSDL displayed in this view represents the WSDL that is exposed to the client. Therefore, it contains only those operations that were selected during the import process, together with any recipient WS-Policy that has been applied to the virtualized web service. You can view the WSDL in its original form under the Resources > WSDL Document Bundles node.
You can add, remove, or edit recipient WS-Policies for the service from this node. For example, to edit an existing recipient WS-Policy, right-click the web service node, and select WS-Policy > Edit
Recipient WS-Policy. If the imported WSDL file included WS-Policy assertions, you can also edit the initiator WS-Policy (for example, to change the signing key). Right-click the web service node and select WS-Policy > Edit Initiator WS-Policy . For more information, see Edit the recipient or initiator WS-Policy on page 96. WSDL resources
A new WSDL document bundle is created for the imported WSDL file under the Resources >
WSDL Document Bundles tree node. This document bundle contains the original WSDL document for the back-end web service, as retrieved at the time of the WSDL import. If multiple versions of this WSDL have been imported, each version is available here. The document bundle also contains the original versions of any resources imported by the WSDL, such as other WSDL files or XML schemas. Axway API Gateway 7.5.2
Policy Developer Guide 102
3 Web services
Click the WSDL document bundle to list the versions that have been imported. Click a particular version to list the WSDL file and any imported WSDL files and XML schemas, as they appeared for that version. To view the source for a WSDL or XML schema file, click the file and a read-only view of that version of the source is displayed. For more information about WSDL document bundles, see Manage WSDL and XML schema documents on page 107.
Policy container
A container for the newly generated policies is created under the Generated Policies node in the Policies tree. The new container is named after the service (for example, Web
Services.HelloWorldService). Policy
A policy for the web service is created in the generated policy container. The policy name is the name of the service (for example, HelloWorldService). This policy contains the Service
Handler for the service. The service handler is an auto-configured Web Service Filter.
Service handler
The Service Handler is used to control and validate requests to the web service and responses from the web service. The Service Handler is named after the web service (for example, Service Handler for 'HelloWorldService'). The Service Handler is a Web
Service Filter, and is used to control the following: l Routing
l Validation
l Message request/response processing
l WSDL options
l Monitoring options
For more details, see Web service filter on page 845.
Security policies
If you configured a WS-policy to enforce security between the client and API Gateway (as described in Configure a security policy on page 90), or if the imported WSDL file contained WS-Policy assertions, a number of additional policies are automatically created in a generated policy container named WSPolicy. Any recipient policies are created in a container named Recipient and any initiator policies are created in a container named Initiator. These generated policies include the filters required to generate and validate the relevant security tokens (for example, SAML tokens, WS-Security UsernameToken elements, and WS-Addressing headers). These policies perform the necessary cryptographic operations (for example, signing/verifying and encryption/decryption) to meet the security requirements of the specified policies.
Export a web service
To export a web service, right-click on the web service node under the Web Service Repository and select Export Web Service.
The following items are exported:
Axway API Gateway 7.5.2
Policy Developer Guide 103
3 Web services
l All circuit containers for the web service, including policies and containers that were generated as part of WS-Policy configuration.
l The current version of the WSDL and its schemas.
Note
If multiple versions of the WSDL are available, only the current version is exported. The complete history of the WSDL is not exported.
l Optionally, other configuration used by the policies can be exported (for example, remote host configuration).
Update a web service
Over the lifetime of a web service, the service definition for the web service can change. You can manage the lifecycle of a web service easily, by using the Resynchronize Web Service option in Policy Studio. This enables you to update the web service definition for a service by revisiting the location of the WSDL.
To update a web service, right-click the web service node, and select Resynchronize Web
Service. You are prompted for the location of the latest version of the WSDL. This defaults to the location from which the WSDL was originally loaded. API Gateway compares the contents of the WSDL and any of its imported schemas to those stored in its cache. If the contents are different, it creates a new version of the WSDL.
Examples of possible updates to the WSDL or XML schemas that trigger creation of a new version are as follows:
l Service name (local part)
If the service name has changed in the WSDL, the import exits with the error "Couldn't
find target Service in this WSDL". You can import this WSDL definition as a new web service using the Register Web Service option.
l WSDL namespace
If the namespace has changed in the WSDL, the import continues with a warning.
Note
Namespace changes result in a new node being created under the Resources >
WSDL Document Bundles tree. Any subsequent resynchronizations of the service result in new versions being added to this node (assuming no further namespace changes).
l WSDL 2.0
If the WSDL has changed to use the WSDL 2.0 specification, import exits with an error. API Gateway supports WSDL 1.1 only, it does not support WSDL 2.0.
l Operation added
If a new operation has been added to a portType in the WSDL, import succeeds. API Gateway regenerates the configuration, using older operations as a template for the WS-Policy settings, if attached. The service handler for the web service is updated to include a resolver for the new operation.
Axway API Gateway 7.5.2
Policy Developer Guide 104
3 Web services
l Operation modified
If an operation has been modified on a portType in the WSDL (for example, changes to the input, output, or fault), import succeeds. API Gateway regenerates the configuration and updates the service handler for the web service.
l SOAPAction
If the SOAPAction has changed for an operation in the WSDL, import succeeds. API Gateway regenerates the configuration and updates the service handler for the web service.
l Operation removed
If an operation has been removed from a portType in the WSDL, import succeeds. API Gateway removes the operation from the configuration. The service handler for the web service is updated to remove the resolver for the removed operation.
l XML schema (when WSDL validation is in use)
If you are using the WSDL to validate incoming messages (this is the default option when you import a WSDL file), and the schemas in the WSDL have been updated, API Gateway retrieves the updated schemas.
Updating a web service is not p ossible for the following types of WSDL or XML schema changes:
l Port, binding, or operation changes that require user intervention for WS-Policy configuration.
l Port change (new endpoint location).
l Port added (SOAP flavor).
l Port change (new binding).
l Binding style or use change.
l WS-Policy added.
l WS-Policy modified.
l WS-Policy removed.
l Operation message part changes (for example, reference to an element changes to a type, part name changes, and so on).
l XML schema changes (when custom schema validation is in use).
Change the operations exposed by a web
service
When you register a web service by importing a WSDL file, you are prompted to select the operations that are to be exposed to the client. You can change the operations that are exposed after import by using the Select Exposed Operations option in Policy Studio. For example, if you imported a web service containing two operations, foo and bar, and you only selected the foo operation at import time, you can use this feature to also expose the bar operation after import.
To change the operations exposed by a web service, right-click the web service node, and select Select Exposed Operations. All of the operations defined in the WSDL file are displayed, and the operations that are currently exposed are selected. Select the operations to be exposed and deselect the operations that are not to be exposed and click OK. Axway API Gateway 7.5.2
Policy Developer Guide 105
3 Web services
API Gateway regenerates the configuration. The service handler for the web service is updated to include resolvers for any newly exposed operations, and to remove resolvers for any removed operations. The WSDL exposed to clients of the virtualized service is updated to reflect the changes. Delete a web service
To delete a web service, right-click on the web service node under the Web Service Repository and select Delete.
Note
To delete the WSDL document or XML schemas associated with a web service, see Delete cached WSDL or XML schema documents on page 112.
Use scripts to manage web services
You can also use scripts to manage web services. The following sample scripts are provided in the INSTALL_DIR/apigateway/samples/scripts/ws directory:
l listWebServices.py – List web services
l registerWebService.py – Register a web service
l removeWebService.py – Delete a web service
You could also create your own custom scripts, for example, to update a web service. However, it would only be possible to script the same type of WSDL or XML schema updates that are supported by the Policy Studio Resynchronize Web Service option. For more information on the types of WSDL or XML schema updates that are supported, see Update a web service on page 104. Publish the WSDL
When the WSDL has been imported into the web service repository, it can be retrieved by clients. In effect, by importing the WSDL into the repository, you are publishing the WSDL. In this way, consumers of the services defined in the WSDL can learn how to communicate with those services by retrieving the WSDL for those services. However, to do this, the location of the service must be changed to reflect the fact that API Gateway now sits between the client and the defined service.
For example, assume that the WSDL file states that a particular service resides at http://www.example.com/services/myService:
<service name="myService">
<port binding="SoapBinding" name="mySample">
<wsdl:address location="http://www.example.com/services/myService"/>
</port>
</service>
Axway API Gateway 7.5.2
Policy Developer Guide 106
3 Web services
When deployed behind API Gateway, this URL is no longer accessible to consumers of the service. Because of this, clients must send SOAP messages through API Gateway to access the service. In other words, they must now address the machine hosting API Gateway instead of that directly hosting the service. When returning the WSDL to the client, API Gateway dynamically changes the value of the location attribute in the service element in the WSDL file to point to the machine on which API Gateway resides. API Gateway is responsible for routing messages on to the machine hosting the service.
Assuming that API Gateway is running on port 8080 on a machine called SERVICES, the location specified in the exported WSDL file is changed to the following:
<service name="myService">
<port binding="SoapBinding" name="mySample">
<wsdl:address location="http://SERVICES:8080/services/myService"/>
</port>
</service>
When the client retrieves this modified WSDL file, it routes messages to the machine hosting API Gateway instead of attempting to directly access the web service. Access the WSDL
For the client to access this modified WSDL file, Policy Studio provides a WSDL retrieval facility whereby clients can query the web service repository for the WSDL file for a particular web service. To do this, the client must specify WSDL on a request query string to the relative path mapped to the policy for this web service. For example, if the policy is deployed under http://SERVICES:8080/services/getQuote,the client can retrieve the WSDL for this web service by sending a request to http://SERVICES:8080/services/getQuote?WSDL. When the client has a copy of the updated WSDL file, it knows how to create correctly formatted messages for the service, and more importantly, it knows to route messages to API Gateway rather than to the web service directly. Publish to UDDI
For details on how to publish a WSDL file registered in the web service repository to a UDDI registry, see Publish WSDL files to a UDDI registry on page 154. Manage WSDL and XML schema documents
Overview
WSDL files often contain XML schemas that define the elements that appear in SOAP messages. When you import a WSDL file to register a web service, the imported WSDL file, and any XML schemas included in the WSDL, are added to a global cache of WSDL and XML schema documents. You can also add XML schemas and WSDL documents to the cache independently. Axway API Gateway 7.5.2
Policy Developer Guide 107
3 Web services
If you select a cached WSDL file or XML schema in a Schema Validation filter, API Gateway can retrieve it from the cache instead of fetching it from its original location. This improves the runtime performance of the filter, and also ensures that an administrator has complete control over the schemas used to validate messages.
API Gateway can maintain multiple versions of WSDL and XML schema documents in the global cache, and keeps an explicit version history as they change over time. The cache is prepopulated with many of the common XML schema documents that are used in web services, and these are shared across multiple web services.
Structure of the global cache
The global cache consists of both WSDL documents and XML schema documents. The global cache of WSDL documents contains all WSDL documents that have been imported (either directly, or by registering a web service) into API Gateway.
The global cache of schema documents contains:
l User-defined catalog – This contains all user-defined schema documents that have been imported into API Gateway.
l System catalog – This contains all common schemas (for example, the SOAP encoding schema) that are preloaded during API Gateway installation.
The following figure shows the structure.
Axway API Gateway 7.5.2
Policy Developer Guide 108
3 Web services
View cached WSDL or XML schema documents
Policy Studio provides a read-only view of cached WSDL and XML schema documents.
To view the global cache of WSDL documents, expand the Resources > WSDL Document
Bundles tree node. The list of documents present in the cache is shown in the tree. To view the contents of a document, click the document node. A read-only view of the document is displayed in a tab on the right. WSDL documents can be added directly to this node, and they can be resynchronized.
To view the global cache of XML schema documents, expand the Resources > XML Schema
Document Bundles tree node. This node contains two subnodes: User-defined Catalog and System Catalog. To view the documents in each catalog, expand the catalog node. The list of documents present in the catalog is shown in the tree. To view the contents of a document, click the document node. A read-only view of the document is displayed in a tab on the right.
XML schemas in the System Catalog are preloaded during API Gateway installation. You cannot add schemas to the system catalog, and schemas in the system catalog cannot be resynchronized. This is indicated by a key icon on these nodes. Axway API Gateway 7.5.2
Policy Developer Guide 109
3 Web services
The User-defined Catalog contains schemas that you have imported. These schemas can be resynchronized, and you can add new schemas directly to this catalog.
Document bundles are categorized by namespace/name, with subcategories used to indicate where the node is being tracked from (the URL it was retrieved from), and further subcategories for version information. The following figure shows an example of this.
Click a document bundle in the tree to list the versions that have been imported. Click a version to list all the documents contained in that version. Click a WSDL or XML schema document to view the WSDL or XML source for the document. A read-only view of the source is shown in a tab on the right. Add XML schemas to the cache
To add an XML schema to the user-defined catalog in the global cache, perform the following steps:
1. In the Policy Studio tree, right-click the XML Schema Document Bundles > User-defined
Catalog node, and select Add Schema. The Load Schema dialog enables you to load a schema directly from the file system. 2. In the File location field, enter or browse to the location of the schema file and click Next.
3. In the Retrieve and Validate window, enter a user name and a comment for this version of the schema. Click Next. Note
If the XML schema fails validation, an error is displayed. For more information, see XML schema and WSDL document validation on page 113 and XML schema and WSDL document limitations on page 113.
4. Click the Finish button to import the schema into the cache. Axway API Gateway 7.5.2
Policy Developer Guide 110
3 Web services
Add WSDL documents to the cache
WSDL documents are cached automatically when you import a WSDL file to register a web service. For more information, see Configure policies from WSDL files on page 86.
Alternatively, you can import a WSDL document directly into the cache. To add a WSDL to the global cache, perform the following steps:
1. In the Policy Studio tree, right-click the WSDL Document Bundles node, and select Add a
WSDL. The Load WSDL dialog enables you to load a WSDL file directly from the file system, from a URL, or from a UDDI registry. 2. Select the appropriate option and enter or browse to the location of the WSDL file in the fields provided. To retrieve the WSDL file from a UDDI registry, click the WSDL from UDDI option, and click the Browse UDDI button. This option enables you to connect to a UDDI registry and search it for a particular WSDL file. For more information on how to retrieve a WSDL file from a UDDI registry, see Retrieve WSDL files from a UDDI registry on page 143. Click Next to continue.
3. In the Retrieve and Validate window, enter a user name and a comment for this version of the WSDL. 4. Click the Finish button to import the WSDL document into the cache. Note
If the WSDL fails validation, an error is displayed. For more information, see XML schema and WSDL document validation on page 113 and XML schema and WSDL document limitations on page 113.
If you import a WSDL document directly into the cache using the WSDL Document
Bundles node, Policy Studio does not automatically generate policies and service handlers. To auto-generate policies and service handlers for a web service, you must use the Register Web Service option under the APIs > Web Service Repository node.
Update cached WSDL or XML schema
documents
You can update a WSDL document or XML schema in the cache by using the Resynchronize
WSDL or Resynchronize Schema options. This enables you to import a more recent version of a WSDL or schema directly to the global cache.
To update a WSDL, perform the following steps:
1. Expand the WSDL Document Bundles node.
2. Expand the document bundle for the WSDL to be updated.
3. Right-click the Tracking from node and select Resynchronize WSDL.
4. Enter the location of the latest version of the WSDL and click Next. This defaults to the location from which the WSDL was originally loaded.
Axway API Gateway 7.5.2
Policy Developer Guide 111
3 Web services
5. In the Retrieve and Validate window, enter a user name and a comment for this version of the WSDL.
6. Click Finish to import the new version of the WSDL document into the cache.
API Gateway compares the contents of the WSDL and any of its imported schemas to those stored in its cache. If the contents are different, it creates a new version of the WSDL.
To update an XML schema, perform the following steps:
1. Expand the XML Schema Document Bundles > User-defined Catalog node.
2. Expand the document bundle for the schema to be updated.
3. Right-click the Tracking from node and select Resynchronize Schema.
4. Enter the location of the latest version of the schema and click Next. This defaults to the location from which the schema was originally loaded.
5. In the Retrieve and Validate window, enter a user name and a comment for this version of the schema.
6. Click Finish to import the new version of the schema document into the cache.
API Gateway compares the contents of the schema and any of its imported schemas to those stored in its cache. If the contents are different, it creates a new version of the schema.
See Update a web service on page 104 for more information on the types of changes to a WSDL or schema that trigger creation of a new version.
Delete cached WSDL or XML schema
documents
You can delete a WSDL document or XML schema in the cache by using the Remove Tracking
Details option. To delete a WSDL, perform the following steps:
1. Expand the WSDL Document Bundles node.
2. Expand the document bundle for the WSDL to be deleted.
3. Right-click the Tracking from node and select Remove Tracking Details.
4. Click Yes to confirm the removal.
API Gateway removes the WSDL from the cache.
To delete an XML schema from the user-defined catalog, perform the same steps under the XML
Schema Document Bundles > User-defined Catalog node.
Axway API Gateway 7.5.2
Policy Developer Guide 112
3 Web services
XML schema and WSDL document validation
XML schemas and WSDL documents are validated during import. If validation fails, an error is displayed. For example, validation fails if a schema type is referenced in a WSDL or schema, but that WSDL or schema does not contain an explicit import statement for the schema that contains the type definition for the referenced type. Note
API Gateway requires all XML schemas and WSDL documents to be present and valid at runtime, and applies very strict validation checks during import. Therefore, WSDL documents that validate successfully in other tools do not necessarily validate in API Gateway, and you might need to preprocess any XML schemas or WSDL documents to make them valid, before attempting to import them in Policy Studio.
A good starting place is to ensure that all WSDLs and their schemas are Web Service Interoperability (WS-I) compliant before attempting to import them into Policy Studio. WS-I compliance ensures maximum interoperability between different vendors' implementation of web services standards, such as SOAP and WSDL. For more information on how to test for WS-I compliance, see Test a WSDL for WS-I compliance on page 115.
An out-of-the-box installation of API Gateway contains a number of common XML schemas (for example, from OASIS and W3C) preloaded in the global cache. If you import a WSDL that imports any of these standard schemas, API Gateway uses the cached version of those schemas, instead of retrieving them from the web. For example, the SOAP encoding schema is often imported into WSDLs that serialize message parts as SOAP encoding arrays. When such a WSDL is imported into Policy Studio, it recognizes that this schema already exists in the cache and does not download and import a duplicate version. This optimization avoids unnecessary duplication of shared schema resources and reduces the overall memory footprint of the API Gateway's configuration store. For more information, see Version and duplicate management on page 115.
XML schema and WSDL document limitations
There are some additional limitations when importing XML schema or WSDL documents:
l Non-SOAP bindings
Any HTTP and MIME bindings in the WSDL document are ignored, and only SOAP 1.1 and SOAP 1.2 bindings are imported. l Multiple ports for the same service
If the WSDL contains multiple ports for the same service (for example, a service is available over SSL and in the clear, where the URL differs, but the binding is to the same SOAP service), you can select only one of the ports for import. If you absolutely require both endpoints to be virtualized on API Gateway, you can create a separate service for each port in the WSDL. A distinct service handler is created for each service, which is responsible for processing requests for that service and routing them on to the endpoint URL specified in the port.
Axway API Gateway 7.5.2
Policy Developer Guide 113
3 Web services
l Schemas using the XML Schema namespace to extend element types, but not
importing the namespace explicitly
Although some tools can work with invalid schemas like this, API Gateway requires them to be valid so it can run schema validation checks against the messages. The schema must be modified to import the namespace explicitly before you can import the schema in Policy Studio. l SOAP bodies with no children
For a SOAP binding style of "document", API Gateway does not support any operation whose request SOAP Body has no child element. l Input-only SOAP operations
API Gateway does not currently support input-only SOAP operations, as these operations have no concept of a response message, and API Gateway has problems generating the Web Service
Filter for these operations. When a Web Service Filter is generated as a result of virtualizing a web service, it handles both the request and response messages for the operations that are exposed by that service. Because input-only or notification-style SOAP operations have no concept of a response message, the Web Service Filter is not ideal, and a custom policy is recommended instead.
l Output-only SOAP operations
API Gateway does not currently support output-only SOAP operations, as API Gateway has problems generating the Web Service Filter for these operations. Similar to input-only operations, output-only or solicit-response operations cause difficulties for a generated Web Service Filter and a custom policy is recommended to process this type of request instead.
l Multiple bindings with different WS-Policy requirements
This results in multiple sets of security requirements that need to be configured by the user, and this is not currently supported by the Import WSDL wizard in Policy Studio. l WSDL messages that contain multiple parts
API Gateway does not support importing a WSDL where the <wsdl:message> contains multiple parts. A workaround is to change the WSDL so that each <wsdl:message> contains a single <wsdl:part> that references a schema complex type that wraps the message parts currently defined in each <wsdl:message>. l Schemas without the schemaLocation attribute
API Gateway requires schemas to import other schemas using both the namespace and schemaLocation attributes, except in the following circumstances:
o The schemas are embedded in the WSDL. The schemaLocation attribute can be omitted from the schema import element and the schema resolver looks for the imported schemas in the WSDL itself.
o The schemas import a schema from the system catalog (which comes preloaded with a number of common schemas, for example, the SOAP encoding schema). A schema from the system catalog can be imported into any schema using just the namespace attribute.
Axway API Gateway 7.5.2
Policy Developer Guide 114
3 Web services
Version and duplicate management
API Gateway manages the resources associated with any WSDL documents or XML schema documents stored in the global cache. This includes the WSDL or XML schema documents themselves, and any WSDL or XML schemas imported by those documents.
When a new resource is being added to the global cache (for example, when you import a WSDL or add a new XML schema), API Gateway compares each resource against the existing resources in the cache. API Gateway tracks two items for each resource:
l The location of the resource
l The contents of the resource at that location
By tracking these two items, API Gateway can identify when a resource is a new version of an existing resource at the same location, or when a resource is the same as an existing resource at a different location. In both cases a new version of the resource is created.
This means that resources that are shared by multiple web services are not duplicated in the global cache, and that web services can be updated easily if the WSDL defining the back-end web service changes. For more information on updating a web service, see Update a web service on page 104. A common example of this is where a vendor implements multiple web services that share common data structures, for example, an object that stores employee details. When the WSDL and schema files for these services are generated, they typically all import a common schema file that defines the employee details data structure. On importing these WSDLs into Policy Studio, API Gateway recognizes that the services all share a common employees schema, and avoids importing multiple copies of the schema into the cache. Instead, each imported web service points at the common schema.
Validate messages against XML schemas
The Schema Validation filter is used to validate XML messages against schemas stored in the cache. It can be configured to validate messages against schemas stored in the cache, and also against schemas embedded within WSDL stored in the cache. This filter is found in the Content
Filtering category of filters in P olicy Studio. For more information on configuring this filter, see Schema validation on page 605.
Test a WSDL for WS-I compliance
Before importing a WSDL file, you can check it for compliance with the WS-I Basic Profile. The Basic Profile consists of a set of assertions and guidelines on how to ensure maximum interoperability between different implementations of web services. For example, there are recommendations on what style of SOAP to use ( document/literal), how schema information is included in WSDL files, and how message parts are defined to avoid ambiguity for consumers of WSDL files. Axway API Gateway 7.5.2
Policy Developer Guide 115
3 Web services
Policy Studio uses the Java version of the WS-I testing tools to test imported WSDL files for compliance with the recommendations in the Basic Profile. A report is generated showing which recommendations have passed and which have failed. While you can still import a WSDL file that does not comply with the Basic Profile, there is no certainty that consumers of the web service can use it without encountering problems. Note
Before you run the WS-I compliance test, you must ensure that the Java version of the WSI testing tools is installed on the machine on which Policy Studio is running. You can download these tools from www.ws-i.org. To configure the location of the WS-I testing tools, select Window > Preferences from the Policy Studio main menu. In the Preferences dialog, select WS-I Settings, and browse to the location of the WS-I testing tools. You must specify the full path to these tools (for example, C:\Program
Files\WSI_Test_Java_Final_1.1\wsi-test-tools). For more details on configuring WS-I settings, see Policy Studio preferences on page 190. Run the WS-I compliance test
To run the WS-I compliance test on a WSDL file, perform the following steps:
1. Select Tools > Run WS-I Compliance Test from the Policy Studio main menu.
2. In the Run WS-I Compliance Test dialog, browse to the WSDL File or specify the WSDL
URL.
3. Click OK. The WS-I analysis tools run in the background in Policy Studio.
The results of the compliance test are displayed in your browser in a WS-I Profile Conformance
Report. The overall result of the compliance test is displayed in the Summary. The results of the WS-I compliance tests are grouped by type in the Artifact:description section. For example, you can access details for a specific port type, operation, or message b y clicking the link in the Entry
List table. Each Entry displays the results for the relevant WS-I test assertions.
Manage JSON schemas
JSON schemas d efine the structure of JSON data. For more details on JSON schemas, see http://www.json-schema.org.
You can manage JSON schemas and schema containers under the Resources > JSON Schemas node in the Policy Studio tree. Add JSON schema
To add a JSON schema, right-click the JSON Schemas node and select Add Schema. Browse to the location on the JSON file on disk and click Open.
You can also view or edit existing schemas. To view a schema, double-click it in the tree. The JSON is displayed on the right. You can edit the JSON in this view. Click Save JSON in the toolbar to save the changes. Axway API Gateway 7.5.2
Policy Developer Guide 116
3 Web services
Add JSON schema container
Schema containers are used to group related schemas. To add a JSON schema container, right-click the JSON Schemas node and select Add Schema Container.
Manage data maps
Data maps enable you to define how to map XML and JSON messages to other XML and JSON message formats. Mappings can be from XML to XML, XML to JSON, JSON to JSON or JSON to XML. You select the source and target XML or JSON schemas in the Data Map dialog and then in the Data Map Editor you define the mapping between the source and target schemas.
To manage data maps, use the Resources > Data Maps node in the Policy Studio tree.
Add data map
To define a new data map, follow these steps:
1. Right-click the Data Maps node and select Add New Data Map. The Data Map dialog screen is displayed.
2. Enter a unique Name for the data map.
Axway API Gateway 7.5.2
Policy Developer Guide 117
3 Web services
3. Enter the information for the Source Schema Details (map from) and the Target Schema Details section (map to). Both sections share the following common fields:
l Type: Select the type of the schema, XML or JSON. Choose XML if the schema is defined by an XSD, or choose JSON if the schema is defined as a JSON schema. You can choose one of four possible schema types depending on the required mapping type:
Mapping Type
Source Schema Type
Target Schema Type
XML to XML
XML
XML
JSON to JSON
JSON
JSON
XML to JSON
XML
JSON
JSON to XML
JSON
XML
l Select the Locate schema on disk check box if the schema definition is located in a file. If the type is XML, it is typical to select an XSD file. If the type is JSON, it is typical to select a JSON file that contains the JSON schema definition. Deselect this option to use an XSD or JSON schema that you have previously imported into API Gateway (for example, under Resources > JSON Schemas, Resources > XML Schema
Document Bundles, or Resources > WSDL Document Bundles).
l Schema: This field is read only. Click the Browse button (to the right of this field) to select a schema. For more information, see Manage JSON schemas on page 116 and Manage WSDL and XML schema documents on page 107.
o If you selected the Locate schema on disk option you can select the schema file on the file system. If the Type is XML, you can select an XSD file containing the schema definition. If the Type is JSON, you can select a JSON file containing the JSON schema definition. o If you did not select the Locate schema on disk option, you can select from the schemas that you previously imported into API Gateway (for example, under Resources > JSON Schemas, Resources > XML Schema Document
Bundles, or Resources > WSDL Document Bundles).
l Root Node: The root node applies to XML schemas only. If there is more than one root element in the XML schema, you are presented with a list of all elements that exist at the root node level. You must select one of these elements for the mapping. If there is only one root element, this root element is listed and selected automatically.
l Engine: This read-only field displays the XSLT processor used by the data map (for example, Saxon).
4. When you have completed the fields, click OK to open the map for editing in the Data Map Editor Design view. For more information on Visual Mapper and the Data Map Editor, see the API Gateway Visual Mapper User Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 118
3 Web services
Tip
You can change the colors and other options for the Data Map Editor in the Policy Studio Preferences dialog. For more information, see Policy Studio preferences on page 190
Data map options
To open a data map for editing in the Data Map Editor, select the data map node under Resources
> Data Maps in the Policy Studio tree. The Data Map Editor displays the content of the map and you can make changes. Any changes made to the map must be saved and redeployed. For more information on Visual Mapper and the Data Map Editor, see the API Gateway Visual Mapper User Guide.
Note
The schemas selected for the data map typically cannot change. To use a different schema, you must create a new data map. However, there is one exception to this: you can modify a JSON schema stored in Resources > JSON Schemas after you have created an associated data map. For more information, see Update previously imported JSON schemas on page 119.
The following options are available when you right-click on an existing data map node in the Policy Studio tree:
l Edit – Change the name of the data map or select a different version of the XML schema.
l Copy – Make a copy of the data map. Right-click the Data Maps node and select Paste to paste a copy of the map. A copy of the data map is created and it is opened in the Data Map Editor for editing.
l Export Data Map – Export the data map as API Gateway configuration data to an XML file. You can use File > Import > Import Configuration Fragment to reimport this data map at a later stage.
l Edit Source Schema – Allows you to edit the source schema.
l Edit Target Schema – Allows you to edit the target schema.
l Delete – Delete the data map. If policies exist that use this data map, you must delete them first.
l Show all references – Shows all objects that refer to this data map. Typically, you will see any policies associated with the data map.
l View Source Schema – Displays the source schema definition associated with the data map.
l View Target Schema – Displays the target schema definition associated with the data map.
Update previously imported JSON schemas
You can update a previously imported JSON schema (for example, if you add a new field to the JSON schema, the field will be visible when the associated Data Map is reloaded). To delete or rename a field in the JSON schema, remove any references to this field (for example, links in the associated Data Map) before you change it in the schema. If you attempt to delete the previously imported JSON schema, a message is displayed that states there are Data Maps that depend on the JSON schema. Axway API Gateway 7.5.2
Policy Developer Guide 119
3 Web services
Use a data map in a policy
To use a data map in a policy, follow these steps:
1. In API Gateway > Policies, select the Policy Container where the new policy (for example, Policy Library). 2. Select Add Policy. A blank policy palette is displayed. 3. Select Conversion> Execute Data Map.
Axway API Gateway 7.5.2
Policy Developer Guide 120
3 Web services
4. Drag the Execute Data Map filter to the policy palette. The Execute Data Map screen is displayed: 5. Enter the information for the Execute Data Map filter: l Name: Enter a unique name for the filter.
l Data Map: This field is read only. Click the Browse button (to the right of this field) to select the appropriate data map.
l Default Encoding: The default for this field is UTF-8. You can use a selector to specify the Default Encoding. 6. Select Finish to save the execute data map filter. A simple example is described in the following steps:
1. Define a data map called addressjsonxmlmap that maps a JSON address schema to an XML address schema.
Axway API Gateway 7.5.2
Policy Developer Guide 121
3 Web services
2. Create a policy c alled AddressMap containing an Execute Data Map filter that executes the addressjsonxmlmap data map.
3. Add a relative path for the AddressMap policy so that all requests received by API Gateway on the path /maps/transformaddress are processed by the AddressMap policy. On the HTTP Method tab of the path resolver, set the method to POST.
4. Use a REST client such as POSTMAN to send a POST request to API Gateway containing an address in JSON format. The response should be the address mapped to XML format according to the data map you defined.
For example, send a POST request to the URL:
http://localhost:8080/map/transformaddress
If the body of the request contains the following JSON formatted address:
{
"address": {
"streetAddress": "21 2nd Street",
"city": "New York"
},
"phoneNumber": [
{
"location": "home",
"code": 44
}
]
}
The mapping defined by the addressjsonxmlmap data map results in the following response (an XML formatted address):
<?xml version="1.0" encoding="UTF-8"?>
<addressDetails orderid="12345POST">
<address>
<streetAddress>21 2nd Street</streetAddress>
<city>NEW YORK</city>
</address>
<phoneNumber>
Axway API Gateway 7.5.2
Policy Developer Guide 122
3 Web services
<location>home</location>
<code>44</code>
</phoneNumber>
</addressDetails>
Use external parameters in a data map
When the user chooses a specific Data Map, the Execute Data Map Filter dialog lists all of the external parameters associated with the data map. Initially, the default values are listed. However, you can edit each parameter so it can overwrite parameters with other values (or selectors) if required. This allows you to reuse a single data map in multiple policies; meaning, each policy can have different values assigned to the external parameters. To use external sources in a data map by adding external parameters, follow these steps:
1. Select the data map under Resources > Data Maps to open it in the Data Map Editor.
2. Right-click Parameters and select Insert Parameter.
3. In the Properties pane at the bottom of the window, complete the following fields:
4. Select Finish to save the execute data map filter. You can now configure external parameters on a per filter basis.
Expose a web service as a REST API
Overview
You can import a WSDL file into Policy Studio, and instead of exposing it to a client, invoke it from a policy. For example, in a SOAP to REST use case, the web service is registered in Policy Studio by importing a WSDL file into the web service repository. A REST API is then defined in Policy Studio, which calls a policy to implement the API, and in turn, this policy invokes the web service.
Summary of steps
The steps involved in exposing a SOAP web service as a REST API are summarized as follows:
1. Virtualize a SOAP web service on page 124
2. Define a REST API on page 125
Axway API Gateway 7.5.2
Policy Developer Guide 123
3 Web services
3. Route REST requests through the virtualized SOAP service on page 126
4. Test the REST to SOAP mapping on page 130
Virtualize a SOAP web service
To expose a virtualized version of a SOAP web service on API Gateway, import a WSDL file describing the web service into the web service repository. The following figure shows importing the WSDL for a currency conversion SOAP web service exposed on the URL:
http://www.webservicex.net/CurrencyConvertor.asmx?WSDL
For more information on using the Import WSDL wizard, see Import a WSDL file on page 88.
When you register a web service in Policy Studio, service handlers and policies are autogenerated. The following figure shows the generated policies for the currency conversion service.
Axway API Gateway 7.5.2
Policy Developer Guide 124
3 Web services
Define a REST API
The next step is to define a REST API for a currency conversion service. Follow these steps:
1. Create a new policy container called CurrencyConversion.
2. Within this policy container create a new policy called MainRouter.
3. Add a Policy Shortcut filter to the MainRouter policy, and set it to call the CurrencyConvertor policy that was autogenerated when you imported the WSDL for the web service.
4. Add a Validate REST filter to the MainRouter policy. Set the Method to GET, add two request parameters called fromCurrency and toCurrency, and select the Extract valid
parameters into individual message attributes check box:
5. Add a relative path for the MainRouter policy so that all REST requests received by API Gateway on the path /convertcurrency/getConversionRate are processed by the MainRouter policy. On the HTTP Method tab of the path resolver, set the method to GET.
Axway API Gateway 7.5.2
Policy Developer Guide 125
3 Web services
At this stage, the MainRouter policy should look like this:
Route REST requests through the virtualized
SOAP service
To route REST requests through the virtualized SOAP service, perform the following sequence of tasks:
1. Create a request processing policy on page 126
2. Create a response processing policy on page 129
Create a request processing policy
First, create a dedicated request processing policy to create the SOAP request message body to send to the SOAP service: 1. Create a request processing policy called GetCurrencyConvertorRequest.
2. Add a Set HTTP verb filter to the policy and enter POST in the HTTP Verb field.
3. Add an Add HTTP header filter to the policy with the following settings:
Axway API Gateway 7.5.2
Policy Developer Guide 126
3 Web services
4. Add a Set Message filter to the policy and enter text/xml as the Content-Type.
Select From web service operation from the Populate menu and select the ConversionRate operation from the currency conversion web service. This populates the contents of the message body.
Axway API Gateway 7.5.2
Policy Developer Guide 127
3 Web services
You need to replace the currencies in the message body with the currencies from the incoming REST request. To enable the autocompletion mechanism in the Set Message filter, which will allow you to insert the fromCurrency and toCurrency selector strings in the message body, you must first connect up the filters in the MainRouter and GetCurrencyConvertorRequest policies.
5. Add a Policy Shortcut filter to the MainRouter policy, and set it to call the GetCurrencyConvertorRequest policy. 6. Connect the filters in the MainRouter policy as follows:
7. Connect the filters in the GetCurrencyConvertorRequest policy as follows:
8. Edit the Set Message filter. Select the currency type in the message body and start typing to see matching selectors. 9. Insert the selectors $params.query.fromCurrency and $params.query.toCurrency in place of the currency types.
Axway API Gateway 7.5.2
Policy Developer Guide 128
3 Web services
Create a response processing policy
Next, create a response processing policy to convert the XML returned from the SOAP web service from XML to JSON format:
1. Create a response processing policy called GetCurrencyConvertorResponse.
2. Add an XML to JSON filter to the policy. Configure it to extract the SOAP Body content first and remove any namespaces:
3. The GetCurrencyConvertorResponse policy should now look like this:
4. Add another Policy Shortcut filter to the MainRouter policy, and set it to call the GetCurrencyConvertorResponse policy. Axway API Gateway 7.5.2
Policy Developer Guide 129
3 Web services
At this stage, the MainRouter policy should look like this:
Test the REST to SOAP mapping
To test the REST to SOAP mapping, deploy the configuration on the API Gateway and send a REST request from a REST client. For example, to get the conversion rate for EUR to USD, send a request to the URL:
http://localhost:8080/convertcurrency/getConversionRate?fromCurrency=EUR&toCurrency=
USD
The following is an example JSON response:
{
"ConversionRateResponse": {
"ConversionRateResult": 1.1194
}
}
You can use API Gateway Manager to view the filter execution path for the REST request, and to examine the request from the client and the response from API Gateway, and the request from API Gateway and the response from the web service. Axway API Gateway 7.5.2
Policy Developer Guide 130
3 Web services
For more information on API Gateway Manager, see the API Gateway Administrator Guide.
Develop REST APIs in Policy Studio
Overview
Policy developers can use the REST API development wizard in Policy Studio to create new REST APIs based on existing back-end REST and non-REST APIs in an iterative development cycle. For example, this includes exposing a SOAP web service, or a cloud-based application as a REST API. Creating new REST APIs using Policy Studio is known as API development. You must specify a custom routing policy for REST API methods. You can specify optional policies for request and response processing as required. The REST API Repository node in the Policy Studio tree stores information about REST APIs created using the REST API development wizard. When new REST APIs are added in the REST API
Repository, they can then be registered in API Manager for consumption by API consumers and administration by API administrators. APIs created using the REST API development wizard are registered by importing as a back-end API into API Manager. Registered APIs are governed by the API Gateway using policies defined in the client registry. API administrators can use API Manager to manage registered APIs, and API consumers can use API Manager to consume registered APIs in their client applications. Note
You can use Policy Studio to create new REST APIs that route to custom policies. You must use API Manager to register a front-end REST API that routes to the destination REST API. For more details, see the API Manager API Management Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 131
3 Web services
Virtualized REST APIs
The REST API Repository is displayed under the APIs node in the Policy Studio tree. When a REST API is added to this repository, it becomes virtualized by the API Gateway. A virtualized REST API is assigned a path that gives it a namespace in a running API Gateway instance (for example, /flickr/v1). This means that all of its methods reside under a URL with that path (for example, /flickr/v1/photos). You can view the list of virtualized REST APIs by selecting the APIs node in the tree.
The following example shows a virtualized Flickr REST API:
Note
Because the REST API encompasses an inbound listener and resolver in a running API Gateway instance, the paths associated with the API are also displayed in the tree (for example, under Environment Configuration > Listeners > API Gateway > Default
Services > Paths). These REST API paths are read-only under the Listeners node. You can create or update these paths as described in Virtualize a REST API on page 132.
REST API methods
Each REST API consists of zero or more REST API methods. Each method can provide custom polices for request, routing, and response processing. You can view the list of methods for a virtualized REST API by clicking a specific API node under REST API Repository. The following example shows API methods for a virtualized Flickr API:
Virtualize a REST API
To virtualize a REST API in the repository, perform the steps described in this section.
Axway API Gateway 7.5.2
Policy Developer Guide 132
3 Web services
Define the REST API
Perform the following steps to define the REST API:
1. Right-click the REST API Repository node, and select Add REST API to launch the wizard.
2. Enter a Name for the REST API (for example, Flickr API). 3. Enter a short Summary of the API functionality. 4. Enter the API Version. Defaults to 1.0. 5. For a detailed Description, select to Manually enter a description in the text box. Alternatively, select to Specify markdown file location. The default location is:
${environment.VINSTDIR}/docs/REST_API_NAME/REST_API_NAME.md
For details on writing documentation with Markdown, see http://daringfireball.net/projects/markdown/.
6. Click Next.
Specify exposure settings
Perform the following steps to configure how the REST API is exposed:
1. Specify the details for the inbound path that accepts requests:
l Listening on HTTP: Select the HTTP Services group on which the API listens. Defaults to Default Services.
l Virtual Host: Click the browse button to select a virtual host in the dialog. If no virtual host has already been configured, right-click the HTTP service node (for example, Default Services), and select Add a Virtual Host. For more details, see Configure virtual hosts on page 328.
l Base Path: Enter the base path prefix for the API (for example, /flickr/v1). This is the path that the API Gateway listens on for messages for the REST API. This path gives the API a namespace in the running API Gateway instance, under which its methods can reside (for example, /flickr/v1/getPhoto).
2. Click Finish.
Edit the REST API
When the REST API has been virtualized in the repository, it is displayed when you select the REST API Repository node. At any stage, you can select the REST API in the panel on the right, and click Edit to edit any of its configuration settings. Similarly, click Remove to remove the API from the repository. Axway API Gateway 7.5.2
Policy Developer Guide 133
3 Web services
Virtualize a REST API method
To virtualize a REST API method in the repository, perform the steps described in this section.
Define the method
Perform the following steps to define the REST API method:
1. Right-click a configured REST API node, and select Add API Method to launch the wizard.
2. Enter a Name for the REST API method (for example, Photo Search).
3. Enter a short Summary of the method functionality.
4. For a more detailed Description, select to Manually enter a description in the text box. Alternatively, select to Specify markdown file location. The default location is:
${environment.VINSTDIR}/docs/REST_API_NAME/REST_API_METHOD_NAME.md
For details on writing documentation with Markdown, see http://daringfireball.net/projects/markdown/.
5. Click Next.
Specify exposure settings
Perform the following steps to configure the exposure settings:
1. Specify the details for the inbound path that accepts requests: l HTTP Method: Select the HTTP method (defaults to GET).
l Using path: Enter the path for the REST API method (for example, /getPhoto).
Note
You can also specify path parameters (for example, an inbound path of /getPhoto/{userID}, where userID is a variable part of the path). When you specify an inbound path parameter, the parameter (in this case, userID) is automatically added in the Inbound parameters table below.
l Exposed on: Enter the base path that the method is exposed on. Defaults to the API base path (for example, /flickr/v1). For more details, see Specify exposure settings on page 133.
l Resolved using: Select whether the path is resolved using Exact path match (default) or Longest path match. For more details, see Configure relative paths on page 308. Axway API Gateway 7.5.2
Policy Developer Guide 134
3 Web services
2. Under Inbound parameters, click Add to specify a path parameter exposed by the method, and enter values for the following settings:
l Name: Enter the parameter name (for example, userID).
l Description: Enter a short parameter description.
l Param Type: Select the parameter type from the list. Defaults to query.
l Data Type: Select the data type from the list. Defaults to string.
l Select whether the parameter is Required (unselected by default).
l Select whether to Allow Multiple parameters (unselected by default)
The inbound parameters entered in this table are displayed on the API Manager page for this REST API method. For more details, see Example inbound parameters on page 136.
3. Select whether the inbound request should Fail if unspecified parameters are found (selected by default).
4. Under Content Types, select whether I wish to check inbound content types based on
the following settings. If selected, choose whether to Allow Content Types or Deny Content Types, and select the types that you wish to allow or deny.
5. Under Error Response Codes, click Add to specify an error response exposed by the method, and enter values for the following settings:
l HTTP Response Code: Select or enter the response code name (for example, 400).
l Reason: Select or enter the response code reason (for example, Bad Request).
The response codes entered in this table are displayed on the API Manager page for this REST API method.
Configure policies and monitoring settings
You can specify the following policy and monitoring settings for the API method:
1. Click Next, and select an optional Request Processing policy (for example, to check inbound requests for authentication or authorization).
2. Click Next, and select a required Routing policy, which configures how inbound requests are routed. 3. Click Next to select an optional Response Processing policy (for example, to validate or transform outbound responses). Alternatively, click Finish.
4. Click Next to select Monitoring options to configure how the API method is displayed in the API Gateway Manager and API Gateway Analytics consoles. Alternatively, click Finish. The monitoring options are as follows:
l Monitor API Service usage:
Specifies whether to store message metrics for this API service. This is selected by default.
Axway API Gateway 7.5.2
Policy Developer Guide 135
3 Web services
l Monitor API Service usage per client: Specifies whether to generate reports monitoring which authenticated clients are calling which API services. This is selected by default.
l Monitor client usage:
If you want to generate reports on authenticated clients, but are not interested in which API services they are calling, select this option and deselect Monitoring service
usage per client. l Message attribute:
Enter the message attribute to use to identify authenticated clients. The default authentication.subject.id attribute stores the identifier of the authenticated user (for example, the user name or X.509 Distinguished Name). 5. Click Finish.
Edit the REST API method
When the API method has been virtualized in the repository, it is displayed under the REST API
Repository node. At any stage, you can select the REST API method in the panel on the right, and click Edit to edit any of its configuration settings. Similarly, click Remove to delete the API method from the repository. Example inbound parameters
The REST API method wizard enables you to virtualize REST API methods in the REST API
Repository, and to specify any inbound path parameters (for details, see Specify exposure settings on page 134).
For example, given a virtualized REST API such as the Yahoo Finance API, you can use the REST API method wizard to specify inbound stock quote URL path parameters, which can then be mapped to specific query string parameters. This enables you to expose an inbound path such as /stock/quote/{symbol}, and to map {symbol} to the s parameter in the query string. You can then make parameterized API calls such as the following at runtime:
finance.yahoo.com/d/quotes.csv?s=symbol&f=sb2b3jk
This call returns a stock quote such as the following at runtime:
AMZN 272.99 270.03 185.51 284.72
Supported parameter mappings
The REST API parameter mappings supported by the API Gateway are as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 136
3 Web services
Parameter type
Mapping
Query string
l Query string to query string
l Query string to form body
l Query string to path
l Query string to header
Path
l Path to query string
l Path to form body
l Path to path
l Path to header
Form-encoded body
l Form body to query string
l Form body to form body
l Form body to path
l Form body to header
Header
l Header to query string
l Header to form body
l Header to path
l Header to header
You can configure any required mappings using request, routing, or response policies. For more details, see Configure policies and monitoring settings on page 135. For example, you can use a Set
Header filter to map to a header parameter, or a Scripting or Set Message filter to map to a path or query parameter. How to access parameter values at runtime
When inbound parameters are specified in your REST API, you can access their values on the API Gateway message whiteboard at runtime using the following selectors in your policies:
l ${params.path.param_name}
l ${params.query.param_name}
l ${params.form.param_name}
l ${params.header.param_name}
The API Gateway parses the input parameters and auto-generates the message attributes. The configured mappings take these message attributes and use them for the output parameter values (query, form, path, or header). Axway API Gateway 7.5.2
Policy Developer Guide 137
3 Web services
JSON messages
When the message content is JSON, you can also access fields in the message body using ${params.body.field}. For example, given the following JSON message content:
{
"id":"28a384e7-0b13-4679-ae1c-0c63666d3d8e"
"activities": ["running", "swimming", "cycling"],
"subObject":
"foo": "bar",
"hello": "world",
"yetAnotherObject": {
"array": ["a", "b", "c"],
"val": "greetings from yetAnotherObject"
}
}
}
You can use the following selectors to access the JSON message body content in your policy at runtime:
Selector
Value
${params.body.id}
28a384e70b13-4679ae1c0c63666d3d8e
${params.body.activities[1]}
swimming
${params.body.subObject.hello}
world
${params.body.subObject.yetAnotherObject.array
a
[0]}
For more details, see Select configuration values at runtime on page 854.
Monitor APIs in API Gateway Manager
When you create an API in Policy Studio and register it in API Manager, you can use the API Gateway Manager web console to monitor the API at runtime. Axway API Gateway 7.5.2
Policy Developer Guide 138
3 Web services
When invoking a REST API developed in Policy Studio, by default, the authenticated subject displayed on the Traffic tab is blank:
To override the default behavior, you must set the ${authentication.subject.id} message attribute in one of the policies configured for the API (request, routing, or response). The following shows example shows how to configure this using a Set Attribute filter:
When configured in a policy, the subject is displayed in API Gateway Manager as follows:
For details on using API Gateway Manager, see the API Gateway Administrator Guide. Connect to a UDDI registry
Overview
This topic explains how to configure a connection to a UDDI registry in the Registry Connection
Details dialog. It explains how to configure connections to UDDI v2 and UDDI v3 registries, and how to secure a connection over SSL. Axway API Gateway 7.5.2
Policy Developer Guide 139
3 Web services
Configure a registry connection
Configure the following fields in the Registry Connection Details dialog:
Registry Name:
Enter the display name for the UDDI registry.
UDDI v2:
Select this option to use UDDI v2.
UDDI v3:
Select this option to use UDDI v3.
Inquiry URL:
Enter the URL on which to search the UDDI registry (for example, http://HOSTNAME:PORT/uddi/inquiry).
Publish URL:
Enter the URL on which to publish to the UDDI registry, if required (for example, http://HOSTNAME:PORT/uddi/publishing).
Security URL (UDDI v3):
For UDDI v3 only, enter the URL for the security service, if required (for example, http://HOSTNAME:PORT/uddi/security.wsdl).
Note
For UDDI v3, the Inquiry URL, Publish URL, and Security URL specify the URLs of the WSDL for the inquiry, publishing, and security web services that the registry exposes. These fields can use the same URL if the WSDL for each service is at the same URL. For example, a WSDL file at http://HOSTNAME:PORT/uddi/uddi_v3_registry.wsdl can contain three URLs:
l http://HOSTNAME:PORT/uddi/inquiry
l http://HOSTNAME:PORT/uddi/publishing
l http://HOSTNAME:PORT/uddi/security
These are the service endpoint URLs that Policy Studio uses to browse and publish to the registry. These URLs are not set in the connection dialog, but discovered using the WSDL. However, for UDDI v2, WSDL is not used to discover the service endpoints, so you must enter these URLs directly in the connection dialog.
Max Rows:
Enter the maximum number of entries returned by a search. Defaults to 20.
Registry Authentication:
The registry authentication settings are as follows:
l Type
This optional field applies to UDDI v2 only. The only supported authentication type is UDDI_
GET_AUTHTOKEN.
Axway API Gateway 7.5.2
Policy Developer Guide 140
3 Web services
l Username
Enter the user name required to authenticate to the registry, if required.
l Password
Enter the password for this user, if required.
The user name and password apply to UDDI v2 and v3. These are generally required for publishing, but depend on the configuration on the registry side. HTTP Proxy:
The HTTP proxy settings apply to UDDI v2 and v3:
l Proxy Host
If the UDDI registry location entered above requires a connection to be made through an HTTP proxy, enter the host name of the proxy.
l Proxy Port
If a proxy is required, enter the port on which the proxy server is listening.
l Username
If the proxy has been configured to only accept authenticated requests, Policy Studio sends this user name and password to the proxy using HTTP Basic authentication.
l Password
Enter the password to use with the user name specified in the field above.
HTTPS Proxy:
The HTTPS proxy settings apply to UDDI v2 and v3:
l SSL Proxy Host
If the Inquiry URL or Publish URL uses the HTTPS protocol, the SSL proxy host entered is used instead of the HTTP proxy entered above. In this case, the HTTP proxy settings are not used.
l Proxy Port
Enter the port that the SSL proxy is listening on.
Secure a connection to a UDDI registry
You can communicate with the UDDI registry over SSL. All communication may not need to be over SSL (for example, you may wish publish over SSL, and perform inquiry calls without SSL). For UDDI v2 and v3, you can use a mix of http and https URLs for WSDL and service address locations. You can specify some or all of the Inquiry URL, Publish URL, and Security URL settings as https URLs. For example, with UDDI v3, you could use a single URL like the following:
https://HOSTNAME:PORT/uddi/wsdl/uddi_v3_registry.wsdl
Axway API Gateway 7.5.2
Policy Developer Guide 141
3 Web services
If any URLs (WSDL or service address location) use https , you must configure the Policy Studio so that it trusts the registry SSL certificate. Configure Policy Studio to trust a registry certificate
For an SSL connection, you must configure the registry server certificate as a trusted certificate. Assuming mutual authentication is not required, the simplest way to configure an SSL connection between Policy Studio and UDDI registry is to add the registry certificate to the Policy Studio default truststore (the cacerts file). You can do this by performing the following steps in Policy Studio:
1. Select the Environment Configuration > Certificates and Keys > Certificates node in the Policy Studio tree.
2. Click Create/Import, and click Import Certificate.
3. Browse to the UDDI registry SSL certificate file, and click Open.
4. Click Use Subject on the right of the Alias Name field, and click OK. The registry SSL certificate is now imported into the certificate store, and must be added to the Java keystore.
5. Click Keystore on the Certificate window.
6. Click Browse next to the Keystore field.
7. Browse to the following file:
INSTALL_DIR/policystudio/jre/lib/security/cacerts
8. Click Open, and enter the Keystore password. 9. Click Add to Keystore.
10. Browse to the registry SSL certificate imported earlier, select it, and click OK.
11. Restart Policy Studio. You should now be able to connect to the registry over SSL.
Configure mutual SSL authentication
If mutual SSL authentication is required (if Policy Studio must authenticate to the registry), Policy Studio must have an SSL private key and certificate. In this case, you should create a keystore containing the Policy Studio key and certificate. You must configure Policy Studio to load this file. For example, edit the INSTALL_DIR/policystudio/policystudio.ini file, and add the following arguments:
-Djavax.net.ssl.keyStore=/home/axway/osr-client.jks
-Djavax.net.ssl.keyStorePassword=changeit
This example shows an osr-client.jks keystore file used with Oracle Service Registry (OSR), which is the UDDI registry provided by Oracle.
Note
You can also use Policy Studio to create a new keystore ( .jks) file. Click New keystore instead of browsing to the cacerts file as described earlier.
Axway API Gateway 7.5.2
Policy Developer Guide 142
3 Web services
Retrieve WSDL files from a UDDI registry
Overview
You can use WSDL files to register web services in the Web Service Repository and to add WSDL documents and XML schemas to the global cache. Policy Studio can retrieve a WSDL file from the file system, from a URL, or from a UDDI registry. This topic explains how to retrieve a WSDL file from a UDDI registry. For details on how to register WSDL files, see Manage web services on page 101. For details on how to publish WSDL files, see Publish WSDL files to a UDDI registry on page 154. You can also browse a UDDI registry in Policy Studio directly without registering a WSDL file. Under the APIs node in the tree, right-click the Web Service Repository node, and select Browse
UDDI Registry. UDDI concepts
Universal Description, Discovery and Integration (UDDI) is an OASIS-led initiative that enables businesses to publish and discover web services on the Internet. A business publishes services that it provides to a public XML-based registry so that other businesses can dynamically look up the registry and discover these services. Enough information is published to the registry to enable other businesses to find services and communicate with them. In addition, businesses can also publish services to a private or semi-private registry for internal use. A business registration in a UDDI registry includes the following components:
l Green Pages:
Contains technical information about the services exposed by the business
l Yellow Pages:
Categorizes the services according to standard taxonomies and categorization systems
l White Pages:
Gives general information about the business, such as name, address, and contact information
You can search the UDDI registry according to a whole range of search criteria, which is of key importance to Policy Studio. You can search the registry to retrieve the WSDL file for a particular service. Policy Studio can then use this WSDL file to create a policy for the service, or to extract a schema from the WSDL to check the format of messages attempting to use the operations exposed by the Web service.
For a more detailed description of UDDI, see the UDDI specification. In the meantime, the next section gives high-level definitions of some of the terms displayed in the Policy Studio interface.
Axway API Gateway 7.5.2
Policy Developer Guide 143
3 Web services
UDDI definitions
Because UDDI terminology is used in Policy Studio windows, such as the Import WSDL wizard, the following list of definitions explains some common UDDI terms. For more detailed explanations, see the UDDI specification.
businessEntity
This represents all known information about a particular business (for example, name, description, and contact information). A businessEntity can contain a number of businessService entities. A businessEntity may have an identifierBag, which is a list of name-value pairs for identifiers, such as Data Universal Numbering System (DUNS) numbers or taxonomy identifiers. A businessEntity may also have a categoryBag, which is a list of name-value pairs used to tag the businessEntity with classification information such as industry, product, or geographic codes. There is no mapping for a WSDL item to a businessEntity. When a WSDL file is published, you must specify a businessEntity for the businessService.
businessService
A businessService represents a logical service classification, and is used to describe a web service provided by a business. It contains descriptive information in business terms outlining the type of technical services found in each businessService element. A businessService may have a categoryBag, and may contain a number of bindingTemplate entities. In the WSDL to UDDI mapping, a businessService represents a wsdl:service. A businessService has a businessEntity as its parent in the UDDI registry.
bindingTemplate
A bindingTemplate contains pointers to the technical descriptions and the access point URL of the web service, but does not contain the details of the service specification. A bindingTemplate may contain references to a number of tModel entities, which do include details of the service specification. In the WSDL to UDDI mapping, a bindingTemplate represents a wsdl:port.
tModel
A tModel is a web service type definition, which is used to categorize a service type. A tModel consists of a key, a name, a description, and a URL. tModel s are referred to by other entities in the registry. The primary role of the tModel is to represent a technical specification (for example, WSDL file). A specification designer can establish a unique technical identity in a UDDI registry by registering information about the specification in a tModel. Other parties can express the availability of web services that are compliant with a specification by including a reference to the tModel in their bindingTemplate data. This approach facilitates searching for registered web services that are compatible with a particular specification. tModels are also used in identifierBag and categoryBag structures to define organizational identity and various classifications. In this way, a tModel reference represents a relationship between the keyed name-value pairs to the super-name, or namespace in which the name-value pairs are meaningful. A tModel may have an identifierBag and a categoryBag. In the WSDL to UDDI mapping, a tModel represents a wsdl:binding or wsdl:portType.
Axway API Gateway 7.5.2
Policy Developer Guide 144
3 Web services
Identifier
The purpose of identifiers in a UDDI registry is to enable others to find the published information using more formal identifiers such as DUNS numbers, Global Location Numbers (GLN), tax identifiers, or any other kind of organizational identifiers, regardless of whether these are private or shared. The following are identification systems used commonly in UDDI registries:
Identification
System
Name
tModel Key
Dun and Bradstreet DU-N-S Number
dnb-com:D-U-N-S
uuid:8609C81E-EE1F-4D5A-
Thomas Registry Suppliers
thomasregister-
uuid:B1B1BAF5-2329-43E6-
com:supplierID
AE13-BA8E97195039
B202-3EB13AD01823
Category
Entities in the registry may be categorized according to categorization system defined in a tModel (for example, geographical region). The businessEntity, businessService, and tModel types have an optional categoryBag. This is a collection of categories, each of which has a name, value, and tModel key.
The following are categorization systems used commonly in UDDI registries:
Categorization System
Name
tModel Key
UDDI Type Taxonomy
uddi-org:types
uuid:C1ACF26D-96724404-9D70-39B756E62AB4
North American Industry Classification System (NAICS) 1997 Release
ntis-
uuid:C0B9FE13-179F-
gov:naics:1997
413D-8A5B-5004DB8E5BB2
Example tModel mapping for WSDL portType
The following shows an example tModel mapped for a WSDL portType:
<tModel tModelKey="uuid:e8cf1163-8234-4b35-865f-94a7322e40c3">
<name>
StockQuotePortType
</name>
<overviewDoc>
<overviewURL>
http://location/sample.wsdl
Axway API Gateway 7.5.2
Policy Developer Guide 145
3 Web services
</overviewURL>
</overviewDoc>
<categoryBag>
<keyedReference tModelKey="uuid:d01987d1-ab2e-3013-9be2-2a66eb99d824"
keyName="portType namespace"
keyValue="http://example.com/stockquote/" />
<keyedReference tModelKey="uuid:6e090afa-33e5-36eb-81b7-1ca18373f457"
keyName="WSDL type"
keyValue="portType" />
</categoryBag>
</tModel>
In this example, the tModel name is the same as the local name of the WSDL portType (in this case, StockQuotePortType), and the overviewURL links to the WSDL file. The categoryBag specifies the WSDL namespace, and shows that the tModel is for a portType. Configure a registry connection
You first need to select the UDDI registry to search for WSDL files. Complete the following fields to select or add a UDDI registry:
Select Registry:
Select an existing UDDI registry to browse for WSDL files from the Registry drop-down list. To configure the location of a new UDDI registry, click Add. Similarly, to edit an existing UDDI registry location, click Edit. Then configure the fields in the Registry Connection Details dialog. For more details, see Connect to a UDDI registry on page 139.
Select Locale:
You can select an optional language locale from this list. The default is No Locale. WSDL search
When you have configured a UDDI registry connection, you can search the registry using a variety of different search options on the Search tab. WSDL Search is the default option. This enables you to search for the UDDI entries that the WSDL file is mapped to. You can also do this using the Advanced Search option. The following different types of WSDL searches are available:
WSDL portType (UDDI tModel):
Searches for a uddi:tModel that corresponds to a wsdl:portType. You can enter optional search criteria for specific categories in the uddi:tModel (for example, Namespace of
portType). WSDL binding (UDDI tModel):
Searches for a uddi:tModel that corresponds to a wsdl:binding. You can enter optional search criteria for specific categories in the uddi:tModel (for example, Name of binding, or Binding Transport Type). Axway API Gateway 7.5.2
Policy Developer Guide 146
3 Web services
WSDL service (UDDI businessService):
Searches for a uddi:businessService that corresponds to a wsdl:service. You can enter optional search criteria for specific categories in the uddi:businessService (for example, Namespace of service).
WSDL port (UDDI bindingTemplate):
Searches for a uddi:bindingTemplate that corresponds to a wsdl:port.This search is more complex because a serviceKey is required to find a uddi:bindingTemplate. This means that at least two queries are carried out, first to find the uddi:businessService, and another to find the uddi:bindingTemplate.
For example, a bindingTemplate contains a reference to the tModel for the wsdl:portType. You can use the tModel key to find all implementations ( bindingTemplates) for that wsdl:portType. The search looks for businessServices that have bindingTemplates that refer to the tModel for the wsdl:portType. Then with the serviceKey, you can find the bindingTemplate that refers to the tModel for the wsdl:portType. In all cases, click Next to start the WSDL search. The Search Results tree shows the tModel URIs as top-level nodes. These URIs are all WSDL URIs, and you can use these to generate policies on import by selecting the URI, and clicking the Finish button.
You can click any of the nodes in the tree to display detailed properties about that node in the table below the Search Results tree. The properties listed depend on the type of the node that is selected. You can also right-click a node to edit it (for example, add a description, add a category or identifier node, or delete a duplicate node).
Quick search
The Quick Search option enables you to search the UDDI registry for a specific tModel name or category.
tModel Name:
You can enter a tModel Name for a fine-grained search. This is a partial or full name pattern with wildcard searching as specified by the SQL-92 LIKE specification. The wildcard characters are percent %, and underscore _, where an underscore matches any single character and a percent matches zero or more characters. Categories:
You can select one of the following options to search by:
wsdlSpec
Search for tModels classified as wsdlSpec ( uddi-org:types category set to wsdlSpec). This is the default.
Reusable WSPolicy Expressions
Search for tModels classified as reusable WS-Policy Expressions.
All
Search for all tModels.
Axway API Gateway 7.5.2
Policy Developer Guide 147
3 Web services
Click Next to start the search. The Search Results tree shows the tModel URIs as top-level nodes. These URIs are all WSDL URIs, and you can use these to generate policies on import by selecting the URI, and clicking the Finish button.
You can click any of the nodes in the tree to display detailed properties about that node in the table below the Search Results tree. The properties listed depend on the type of the node that is selected. You can also right-click a node to edit it (for example, add a description, add a category or identifier node, or delete a duplicate node).
Name search
The Name Search option enables you to search for a businessEntity, businessService, or tModel by name. In the Select Registry Data Type, select one of the following UDDI entity levels to search for:
l businessEntity
l businessService
l tModel
You can enter a name in the Name field to narrow the search. You can also use wildcards in the name. The name applies to a businessEntity, businessService, or tModel, depending on which registry entity type has been selected. If no name is entered, all entities of the selected type are retrieved.
Click the Search button to start the search. The search results display the matching entities in the tree. For example, if you enter MyTestBusiness for Name, and select businessEntity, this searches for a businessEntity with the name MyTestBusiness. Child nodes of the matching businessEntity nodes are also shown. tModels are displayed in the results if any child nodes of the businessEntity refer to tModels. Only referred to tModels are displayed. The same applies if you search for a businessService. If you select tModel, and search for tModels, only tModels are displayed.
Note
The tModel URIs shown in the resulting tree may not all be categorized as wsdlSpec according to the uddi-org:types categorization system. You can choose to load any of these URIs as a WSDL file, but you are warned if it is not categorized as wsdlSpec.
As before, you can click any node in the results tree to display properties about that node in the table. You can also right-click a node to edit it (for example, add a description, add a category or identifier node, or delete a duplicate node).
UDDI v3 name searches
By default, a UDDI v3 name search is an exact match. To perform a search using wildcards (for example, %, _, and so on), you must select the approximateMatch find qualifier in the Advanced
Options tab. This applies to anywhere you enter a name for search purposes (for example, Name
Search, Quick Search, and Advanced Search).
Axway API Gateway 7.5.2
Policy Developer Guide 148
3 Web services
Advanced search
The Advanced Search option enables you to search the UDDI registry using any combination of Names, Keys, tModels, Discovery URLs, Categories, and Identifiers. You can also specify the entity level to search for in the tree. All of these options combine to provide a very powerful search facility. You can specify search criteria for any of the categories listed above by right-clicking the folder node in the Enter Search Criteria tree, and selecting the Add menu option. You can enter more than one search criteria of the same type (for example, two Key search criteria). Note
The tModel URIs shown in the resulting tree may not all be categorized as wsdlSpec according to the uddi-org:types categorization system. You can choose to load any of these URIs as a WSDL file, but you are warned if it is not categorized as wsdlSpec.
The following options enable you to add a search criteria for each of the types listed in the Enter
Search Criteria tree. All search criteria are configured by right-clicking the folder node, and selecting the Add menu option.
Names:
Enter a name to be used in the search in the Name field in the Name Search Criterion dialog. For example, the name could be the businessEntity name. The name is a partial or full name pattern with wildcards allowed as specified by the SQL-92 LIKE specification. The wildcard characters are percent %, and underscore _, where an underscore matches any single character and a percent matches zero or more characters. A name search criterion can be used for businessEntity, businessService, and tModel level searches.
Keys:
In the Key Search Criterion dialog, you can specify a key to search the registry for in the Key field. The key value is a Universally Unique Identifier (UUID) value for a registry object. You can use the Key Search Criterion on all levels of searches. If one or more keys are specified with no other search criteria, the keys are interpreted as the keys of the selected type of registry object and used for a direct lookup, instead of a find/search operation. For example, if you enter key1 and key2, and select the businessService entity type, the search retrieves the businessService object with key key1, and another businessService with key key2.
If you enter a key with other search criteria, a key criterion is interpreted as follows:
l For a businessService entity lookup, the key is the businessKey of the services.
l For a bindingTemplate entity lookup, the key is the serviceKey of the binding templates.
l Not applicable for any other object type.
tModels:
You can enter a key in the tModel Key field on the tModel Search Criterion window. The key entered should correspond to the UUID of the tModel associated with the type of object you are searching for. A tModel search criterion may be used for businessEntity, businessService, and bindingTemplate level searches.
Axway API Gateway 7.5.2
Policy Developer Guide 149
3 Web services
Discovery URLs:
Enter a URL in the Discovery URL field on the Discovery URL Search Criterion dialog. The Use
Type field is optional, but can be used to further fine-grain the search by type. You can use a Discovery URL search criterion for businessEntity level searches only.
Categories:
Select a previously configured categorization system from the Type drop-down list in the Category
Search Criterion dialog. This prepopulated with a list of common categorization systems. You can add a new categorization system using the Add button.
In the Add/Edit Category dialog, enter a Name, Description, and UUID for the new category type in the fields provided. When the categorization system has been selected or added, enter a value to search for in the Value field. The Name field is optional.
Identifiers:
Select a previously configured identification system from the Type drop-down list in the Identifier
Search Criterion dialog. This is prepopulated with well-known identification systems. To add a new identification system, click the Add button.
In the Add/Edit Identifier dialog, enter a Name, Description, and UUID for the new identifier in the fields provided.
Select Registry Data Type:
Select one of the following UDDI entity levels to search for:
l businessEntity
l businessService
l bindingTemplate
l tModel
The search also displays child nodes of the matching nodes. tModels are also returned if they are referred to. Advanced options
This tab enables you to configure various aspects of the search conditions specified on the previous tabs. The following options are available:
UDDI Find Qualifier
Description
andAllKeys
By default, identifier search criteria are ORed together. This setting ensures that they are ANDed instead. This is already the default for categoryBag and tModelBag.
Axway API Gateway 7.5.2
Policy Developer Guide 150
3 Web services
UDDI Find Qualifier
Description
approximateMatch (v3)
This applies to a UDDI v3 registry only. Specifies wildcard searching as defined by the uddi-
org:approximatematch:SQL99 tModel, which means approximate matching where percent sign ( %) indicates any number of characters, and underscore ( _) indicates any single character. The backslash character ( \) is an escape character for the percent sign, underscore and backslash characters. This option adjusts the matching behavior for name, keyValue, and keyName (where applicable).
binarySort (v3)
This applies to a UDDI v3 registry only. Enables greater speed in sorting, and causes a binary sort by name, as represented in Unicode codepoints.
bindingSubset (v3)
This applies to a UDDI v3 registry only. Specifies that the search uses only categoryBag elements from contained bindingTemplate elements in the registered data, and ignores any entries found in the categoryBag that are not direct descendents of registered businessEntity or businessService elements.
caseInsensitiveMatch (v3)
This applies to a UDDI v3 registry only. Specifies that that the matching for name, keyValue, and keyName (where applicable) should be performed without regard to case.
caseInsensitiveSort (v3)
This applies to a UDDI v3 registry only. Specifies that the result set should be sorted without regard to case. This overrides the default case sensitive sorting behavior.
caseSensitiveMatch (v3)
This applies to a UDDI v3 registry only. Specifies that that the matching for name, keyValue, and keyName (where applicable) should be case sensitive. This is the default behavior.
caseSensitiveSort (v3)
Axway API Gateway 7.5.2
This applies to a UDDI v3 registry only. Specifies that the result set should be sorted with regard to case. This is the default behavior.
Policy Developer Guide 151
3 Web services
UDDI Find Qualifier
Description
combineCategoryBags
Makes the categoryBag entries of a businessEntity behave as if all categoryBag s found at the businessEntity level and in all contained or referenced businessService s are combined. Searching for a category yields a positive match on a registered business if any of the categoryBags contained in a businessEntity (including the categoryBags in contained or referenced businessServices) contain the filter criteria.
diacriticInsensitiveMatch
(v3)
This applies to a UDDI v3 registry only. Specifies that matching for name, keyValue, and keyName (where applicable) should be performed without regard to diacritics. Support for this qualifier by nodes is optional.
diacriticSensitiveMatch
(v3)
This applies to a UDDI v3 registry only. Specifies that matching for name, keyValue, and keyName (where applicable) should be performed with regard to diacritics. This is the default behavior.
exactMatch (v3)
This applies to a UDDI v3 registry only. Specifies that only entries with name, keyValue, and keyName (where applicable) that exactly match the name argument passed in, after normalization, are returned. This qualifier is sensitive to case and diacritics where applicable. This is the default behavior.
exactNameMatch (v2)
This applies to a UDDI v2 registry only. Specifies that the name entered as part of the search criteria must exactly match the name specified in the UDDI registry.
orAllKeys
By default, tModel and category search criteria are ANDed. This setting ORs these criteria instead.
orLikeKeys
When a bag container contains multiple keyedReference elements ( categoryBag or identifierBag), any keyedReference filters from the same namespace (for example, with the same tModelKey value) are ORed together rather than ANDed. For example, this enables you to search for any of these four values from this
namespace, and any of these two values
from this namespace.
Axway API Gateway 7.5.2
Policy Developer Guide 152
3 Web services
UDDI Find Qualifier
Description
serviceSubset
Causes the component of the search that involves categorization to use only the categoryBags from directly contained or referenced businessServices in the registered data. The search results return only those businesses that match based on this modified behavior, in conjunction with any other search arguments provided.
signaturePresent (v3)
This applies to a UDDI v3 registry only. This restricts the result to entities that contain, or are contained in, an XML Digital Signature element. The Signature element should be verified by the client. This option, or the presence of a Signature element, should only be used to refine a search result, and should not be used as a verification mechanism by UDDI clients.
sortByDateAsc (v3)
This applies to a UDDI v3 registry only. Sorts the results alphabetically in order of ascending date.
sortByDateDsc (v3)
This applies to a UDDI v3 registry only. Sorts the results alphabetically in order of descending date.
sortByNameAsc
Sorts the results alphabetically in order of ascending name.
sortByNameDsc
Sorts the results alphabetically in order of descending name.
suppressProjectedServices
(v3)
This applies to a UDDI v3 registry only. Specifies that service projections must not be returned when searching for services or businesses. This option is enabled by default when searching for a service without a businessKey.
UTS-10 (v3)
This applies to a UDDI v3 registry only. Specifies sorting of results based on the Unicode Collation Algorithm on elements normalized according to Unicode Normalization Form C. A sort is performed according to the Unicode Collation Element Table in conjunction with the Unicode Collation Algorithm on the name field, and normalized using Unicode Normalization Form C. Support for this qualifier by nodes is optional.
Publish
Click the Publish radio button to view the Published UDDI Entities Tree View. This enables you to manually publish UDDI entities to the specified UDDI registry (for example, businessEntity, businessService, bindingTemplate, and tModel entities). You Axway API Gateway 7.5.2
Policy Developer Guide 153
3 Web services
must already have the appropriate permissions to write to the UDDI registry.
Add a businessEntity
To add a business, perform the following steps:
1. Right-click the tree view, and select Add businessEntity.
2. In the Business dialog, enter a Name and Description for the business. Click OK.
3. You can right-click the new businessEntity node to add child UDDI entities in the tree (for example, businessService, Category, and Identifier entities).
Add a tModel
To add a tModel , perform the following steps:
1. Right-click the tree view, and select Add tModel.
2. In the tModel dialog, enter a Name, Description, and Overview URL for the tModel . For example, you can use the Overview URL to specify the location of a WSDL file. Click OK.
3. You can right-click the new tModel node to add child UDDI entities in the tree (for example, Category and Identifier entities).
As before, you can click any node in the results tree to display properties about that node in the table. You can also right-click a node to edit it (for example, add a description, add a category or identifier node, or delete a duplicate node). At any stage, you can click the Clear button on the right to clear the entire contents of the tree. This does not delete the contents of the registry.
For more details on UDDI entities such as businessEntity and tModel, see UDDI definitions on page 144. For details on how to publish web services automatically using a wizard, see Publish WSDL files to a UDDI registry on page 154.
Publish WSDL files to a UDDI registry
Overview
You can register web services in the Web Service Repository using Web Services Description Language (WSDL) files. Policy Studio can retrieve a WSDL file from the file system, from a URL, or from a UDDI registry. When you have registered a WSDL file in the web service repository, you can use the Publish WSDL wizard to publish the WSDL file to a UDDI registry. You can also use the Find WSDL wizard to search for the selected WSDL file in a UDDI registry. This topic explains how to perform both of these tasks.
Axway API Gateway 7.5.2
Policy Developer Guide 154
3 Web services
For background information and an introduction to general UDDI concepts, see Retrieve WSDL files from a UDDI registry on page 143. For details on how to register WSDL files, see Manage web services on page 101.
Find WSDL files
You can search a UDDI registry to determine if a web service is already published in the registry. To search for a selected WSDL file in a specified UDDI registry, perform the following steps:
1. In the Policy Studio tree, expand the APIs > Web Service Repository node.
2. Right-click a WSDL node and select Find in UDDI Registry to launch the Find WSDL wizard.
3. In the Find WSDL dialog, select a UDDI registry from the list. You can add or edit a registry connection using the buttons provided. For details on configuring a registry connection, see Connect to a UDDI registry on page 139.
4. You can select an optional language Locale from the list. The default is No Locale.
5. Click Next. The WSDL Found in UDDI Registry window displays the result of the search in a tree. The Node Counts field shows the total numbers of each UDDI entity type returned from the search ( businessEntity, businessService, bindingTemplate, and tModel).
6. You can right-click to edit a UDDI entity node in the tree, if necessary (for example, add a description, add a category or identifier node, or delete a duplicate node).
7. Click the Refresh button to run the search again.
8. Click Finish.
The Find WSDL wizard provides is a quick and easy way of finding a selected WSDL file published in a UDDI registry. For more fine-grained ways of searching a UDDI registry (for example, for specific WSDL or UDDI entities), see Retrieve WSDL files from a UDDI registry on page 143.
Publish WSDL files
To publish a WSDL file registered in the Web Service Repository to a UDDI registry, perform the following steps:
1. Expand the API > Web Service Repository tree node.
2. Right-click a WSDL node and select Publish WSDL to UDDI Registry to launch the Publish WSDL Wizard.
3. Perform the steps in the wizard as described in the next sections.
Axway API Gateway 7.5.2
Policy Developer Guide 155
3 Web services
Step 1: Enter virtualized service address and WSDL
URL for publishing in UDDI registry
When you register a WSDL file in the web service repository, API Gateway exposes a virtualized version of the web service. The host and port for the web service are changed dynamically to point to the machine running API Gateway. The client can then retrieve the WSDL for the virtualized web service from API Gateway, without knowing its real location. This window enables you to optionally override the service address locations in the WSDL file with the virtualized addresses exposed by API Gateway. You can also override the WSDL URL published to the UDDI registry. Complete the following fields:
Mapping of Service Addresses to Virtualized Service Addresses:
You can enter multiple virtual service address mappings for each service address specified in the selected WSDL file. If you do not enter a mapping, the original address location in the WSDL file is published to the UDDI registry. If one or more mappings are provided, c orresponding UDDI bindingTemplates are published in the UDDI registry, each with a different access point (virtual service address). This enables you to publish the access points of a service when it is exposed on different ports/schemes using API Gateway.
When you launch the wizard, the mapping table is populated with a row for each wsdl:service, wsdl:port, soap:address, soap12:address, or http:address in the selected WSDL file. To modify an existing entry, select a row in the table, and click Edit. Alternatively, click Add to add an entry. In the Virtualize Service Address dialog, enter the virtualized service address. For example, if API Gateway is running on a machine named roadrunner, the new URL on which the web service is available to clients is: http://roadrunner:8080/TestServices/StockQuote.svc.
WSDL URL:
You can enter a WSDL URL to be published to the UDDI registry in the corresponding tModel
overviewURL fields. If you do not enter a URL, the WSDL URL in the Original WSDL URL field is used. For example, an endpoint service is at http://coyote.qa.acmecorp.com/TestService/StockQuote.svc. Assume this service is virtualized in API Gateway and exposed at http://HOST:8080/TestService/StockQuote.svc, where HOST is the machine on which API Gateway is running. The http://HOST:8080/TestService/StockQuote.svc URL is entered as the virtual service address, and http://HOST:8080/TestService/StockQuote.svc?WSDL is entered as the WSDL URL to publish.
Note
If incorrect URLs are published, you can edit these in the UDDI tree in later steps in this wizard, or when browsing the registry. Click Next when finished.
Axway API Gateway 7.5.2
Policy Developer Guide 156
3 Web services
Step 2: View WSDL to UDDI mapping result
You can use this window to view the unpublished mapping of the WSDL file to a UDDI registry structure. You can also edit a specific mapping in the tree view. This window includes the following fields:
Mapping of WSDL to a UDDI Registry Structure:
The unpublished mappings from the WSDL file to the UDDI registry are displayed in the table. For example, this includes the relevant businessService, bindingTemplate, tModel, Identifier, Category mappings. You can select a tree node to display its values in the table below. You can optionally edit the values for a specific mapping in the table (for example, update a value, or add a key or description for the selected UDDI entity). You can also right-click a tree node to edit it (for example, add a description, add a category or identifier node, or delete a duplicate node). Retrieve service address from WSDL instead of bindingTemplate access point:
When selected, this ensures that the bindingTemplate access point does not contain the service port address, and is set to WSDL instead. This means that you must retrieve the WSDL to get the service access point. When selected, the bindingTemplate contains an additional tModelInstanceInfo that points to the uddi:uddi.org.wsdl:address tModel. This option is not selected by default.
Include WS-Policy as:
When selected, you can choose one of the following options to specify how WS-Policy statements in the WSDL file are included in the registry:
Remote
Policy
Expressions
Each WS-Policy URL in the WSDL that is associated with a mapped UDDI entity is accessed remotely. For example, a businessService is categorized with the uddi:w3.org:ws-
policy:v1.5:attachment:remotepolicyreference tModel where the keyValue holds the remote WS-Policy URL. This is the default option. Reusable
Policy
Expressions
Each WS-Policy URL in the WSDL that is associated with a mapped UDDI entity has a separate tModel published for it. Other UDDI entities (for example, businessService) can then refer to these tModels. These are reusable because UDDI entities published in the future can also use these tModels. You can do this in Step 4: Select a duplicate publishing approach on page 158, by selecting the Reuse duplicate tModels option.
Click Next when finished.
Step 3: Select a registry for publishing
Use this window to select a UDDI registry in which to publish the WSDL to UDDI mapping. Complete the following fields:
Axway API Gateway 7.5.2
Policy Developer Guide 157
3 Web services
Select Registry:
Select an existing UDDI registry to browse for WSDL files from the Registry drop-down list. To configure the location of a new UDDI registry, click Add. Similarly, to edit an existing UDDI registry location, click Edit. For details on how to configure a UDDI connection, see Connect to a UDDI registry on page 139.
Select Locale:
You can select an optional language locale from this list. The default is No Locale. Click Next when finished.
Step 4: Select a duplicate publishing approach
This window is displayed only if mapped WSDL entities already exist in the UDDI registry. Otherwise, the wizard skips to Step 5: Create or search for business on page 159. This window includes the following fields:
Select Duplicate Mappings:
The Mapped WSDL to publish pane on the left displays the unpublished WSDL mappings from Step 2: View WSDL to UDDI mapping result on page 157. The Duplicates for WSDL mappings
in UDDI registry pane on the right displays the nodes already published in the registry. The Node
List at the bottom right shows a breakdown of the duplicate nodes.
Edit Duplicate Mappings:
You can eliminate duplicate mappings by right-clicking a tree node in the right or left pane, and selecting edit to update a specific mapping in the dialog. Select the Refresh button on the right to run the search again, and view the updated Node List. Alternatively, you can configure the options in the next field. Select Publishing Approach for Duplicate Entries:
Select one of the following options:
Reuse
duplicate
tModels
Publishes the selected entries from the tree on the left, and reuses the selected duplicate entries in the tree on the right. This is the default option. Some or all duplicate tModels (for example, for portType, binding, and reusable WSPolicy expressions) that already exist in the registry can be reused. This means that a new businessService that points to existing tModels is published. Any entries selected on the left are published, and any referred to tModels on the left now point to selected duplicate tModels on the right. By default, this option selects all businessServices on the left, and all duplicate tModels on the right. If there is more than one duplicate tModels, only the first is selected.
Axway API Gateway 7.5.2
Policy Developer Guide 158
3 Web services
Overwrite
duplicates
Publishes the selected entries from the tree on the left, and overwrites the selected duplicate entries in the tree on the right. When a UDDI entity is overwritten, its UUID key stays the same, but all the data associated with it is overwritten. This is not just a transfer of additions or differences. You can also overwrite some duplicates and create some new entries. By default, this option selects all businessServices and tModels on the left and all duplicate businessServices and tModels on the right. If there is more than one duplicate, only the first is selected. The default overwrites all selected duplicates and does not create any new UDDI entries, unless there is a new referred to tModel (for example, for a reusable WS-Policy expression).
Ignore
duplicates
Publishes the selected entries from the tree on the left, and ignores all duplicates. You can proceed to publish the mapped WSDL to UDDI data. New UDDI entries are created for each item that is selected in the tree on the left.
Click Next when finished.
Note
If you select duplicate businessServices in the tree, and select Overwrite
duplicates, the wizard skips to Step 6: Publish WSDL on page 160 when you click Next.
Step 5: Create or search for business
Use this window to specify a businessEntity for the web service. You can create a new businessEntity or search for an existing one in the UDDI registry. Complete the following fields:
Create a new businessEntity:
This is the default option. Enter a Name and Description for the businessEntity, and click Publish.
Search for an existing businessEntity:
To search for an existing businessEntity name, perform the following steps:
1. Select the Search for an existing businessEntity in the UDDI registry option.
2. In the Search tab, ensure the Name Search option is selected.
3. Enter a Name option (for example, Acme Corporation).
Alternatively, you can select the Advanced Search option to search by different criteria such as Keys, Categories, or tModels. You can also select a range of search options on the Advanced tab (for example, Exact match, Case sensitive, or Service subset). For more details, see Retrieve WSDL files from a UDDI registry on page 143. The Node Counts field shows the total numbers of each UDDI entity type returned from the search ( businessEntity, businessService, bindingTemplate,and tModel).
Click Next when finished.
Axway API Gateway 7.5.2
Policy Developer Guide 159
3 Web services
Step 6: Publish WSDL
Use this to publish the WSDL to the UDDI registry. Selected businessEntity for Publishing:
This field displays the name and tModel key of the businessEntity to be published. Click the Publish WSDL button on the right.
Published WSDL:
This field displays the tree of the UDDI mapping for the WSDL file. You can right-click to edit or delete any nodes in the tree if necessary, and click Refresh to run the search again. Click Publish
WSDL to publish your updates.
Click Finish.
Axway API Gateway 7.5.2
Policy Developer Guide 160
Messaging
4
This section describes how to configure messaging services.
Configure messaging services
161
Configure a JMS service
163
Configure a JMS session
167
Configure a JMS consumer
169
Send to JMS
172
Read from JMS
176
Configure messaging services
Overview
A messaging system is a loosely coupled, peer-to-peer facility where clients can send messages to, and receive messages from any other client. In a messaging system, a client sends a message to a messaging agent. The recipient of the message can then connect to the same agent and read the message. However, the sender and recipient of the message do not need to be available at the same time to communicate (for example, unlike HTTP). The sender and recipient need only know the name and address of the messaging agent to talk to.
Java Message Service (JMS) is an implementation of such a messaging system. It provides an API for creating, sending, receiving, and reading messages. Java-based applications can use it to connect to other messaging system implementations. A JMS provider c an deliver messages synchronously or asynchronously, which means that the client can fire and forget messages or wait for a response before resuming processing. Furthermore, the JMS API ensures different levels of reliability in terms of message delivery. For example, it can ensure that the message is delivered once and only once, or at least once.
API Gateway uses the JMS API to connect to other messaging systems that expose a JMS interface (for example, Oracle WebLogic Server, IBM WebSphere MQ, Red Hat JBoss Messaging, Apache ActiveMQ, or Progress SonicMQ). As a consumer of a JMS queue or topic, the API Gateway can read XML messages and pass them into a policy for validation. These messages can then be routed on over HTTP or dropped on to another JMS queue or topic. API Gateway also provides a default embedded Apache ActiveMQ service, which enables it to act as a JMS server. For example, this enables API Gateway to integrate external facing REST APIs and SOAP Web services with back-end systems and applications using reliable asynchronous messaging.
Axway API Gateway 7.5.2
Policy Developer Guide 161
4 Messaging
Prerequisites
API Gateway provides all the required third-party JAR files for IBM WebSphere MQ and Apache ActiveMQ (both embedded and external).
Note
For other third-party JMS providers only, you must add the required third-party JAR files to the API Gateway classpath for messaging to function correctly. If the provider's implementation is platform-specific, copy the provider JAR files to INSTALL_
DIR/ext/PLATFORM.
INSTALL_DIR is your API Gateway installation, and PLATFORM is the platform on which API Gateway is installed ( Win32, Linux.i386, or SunOS.sun4u-32). If the provider implementation is platform-independent, copy the JAR files to INSTALL_
DIR/ext/lib.
Configure API Gateway messaging using the
JMS wizard
You can use the JMS Wizard to configure an API Gateway instance to consume JMS messages from a JMS queue or topic. When a message has been consumed by the API Gateway, it can be sent to a configured policy where the full range of API Gateway message filters can run on the message. The message can then be routed onwards over HTTP or dropped back on to a JMS queue or topic. The JMS Wizard guides you through all of the necessary steps to configure messaging (for example, the JMS service, JMS session, and JMS consumer).
To launch the JMS Wizard , right-click the instance under the Environment Configuration > Listeners node in the Policy Studio tree, and select Messaging System > JMS Wizard. The wizard includes the following windows:
JMS Service Provider
The first window in the wizard enables you to configure connection details to the JMS provider that produces the JMS messages that are consumed by the API Gateway. For details on configuring the fields on this window, see Configure a JMS service on page 163. Click Next when finished. JMS Session Configuration
The second window in the wizard enables you to configure settings such as Remove message
from source for the JMS session that is established with the JMS provider. For details on configuring these settings, see Configure a JMS session on page 167. Click Next when finished. JMS Consumer Configuration
The third window in the wizard enables you to configure JMS consumer settings. For details on configuring the fields on this window, see Configure a JMS consumer on page 169. Click Finish to complete. Axway API Gateway 7.5.2
Policy Developer Guide 162
4 Messaging
Configure global JMS services in external
connections
Alternatively, you can configure a global JMS service under the Environment Configuration > External Connections node in Policy Studio by right-clicking the JMS Services node, and selecting Add a JMS Service. The configured global JMS services can then be used by the API Gateway to drop messages on to a JMS queue or topic, or to read messages from a JMS queue or topic (for example, using the Send
to JMS or Read from JMS filter). For more details, see Configure a JMS service on page 163.
Configure embedded Apache ActiveMQ in API
Gateway settings
You can use the API Gateway server settings to configure the default embedded Apache ActiveMQ broker available in API Gateway, and which enables it to act as a JMS service provider. In the Policy Studio tree, select Environment Configuration > Server Settings > Messaging
> Embedded ActiveMQ. For example, you can enable embedded ActiveMQ, and configure location and SSL security settings. For more details, see the API Gateway Administrator Guide. Monitor messaging using API Gateway Manager
You can use the API Gateway Manager web console to monitor messaging at runtime. For example, you can create, delete, and view JMS topics, queues, and messages at runtime.
For more details, see the API Gateway Administrator Guide. Configure a JMS service
Overview
You can configure a global JMS service under the Environment Configuration > External
Connections node in Policy Studio by right-clicking the JMS Services node, and selecting Add a
JMS Service . The details entered in the JMS Service dialog can then be used by the API Gateway to drop messages on to a JMS queue or topic, or to read messages from a JMS queue or topic. For more details, see the following filters:
Axway API Gateway 7.5.2
Policy Developer Guide 163
4 Messaging
l Send to JMS on page 172
l Read from JMS on page 176
Alternatively, you can configure a JMS service at the API Gateway instance level, and configure the API Gateway to consume a JMS queue or topic. Right-click the instance under the Environment
Configuration > Listeners node in the Policy Studio, and select JMS Wizard.
General configuration
Configure the following fields on the JMS Service tab:
Name:
Enter a descriptive name for the JMS provider in the Name field. Service type:
Select one of the following from the list:
l Embedded Apache ActiveMQ: The default Apache ActiveMQ service that is embedded in the API Gateway.
l Apache ActiveMQ: An external Apache ActiveMQ service that is not embedded in the API Gateway.
l IBM MQ: An IBM WebSphere MQ service. See IBM WebSphere MQ settings on page 165.
l Standard JMS: Other systems that support the JMS standard (for example, Oracle WebLogic Server, IBM MQSeries, JBoss Messaging, or Progress SonicMQ).
Apache ActiveMQ and Standard JMS settings
The following settings are displayed when you select a Service Type of Embedded Apache ActiveMQ, Apache ActiveMQ, or Standard JMS:
Provider URL:
Enter the URL of the JMS provider. For example, a URL for a JBoss application server might be jnp://localhost:1099. Defaults to local for Embedded Apache ActiveMQ.
Initial Context Factory:
API Gateway uses a connection factory to create a connection with a JMS provider. A connection factory encapsulates a set of connection configuration parameters that have been defined by the administrator. The following are some example default values:
l Embedded Apache ActiveMQ: com.vordel.ama.jndi.InitialContextFactory
l External Apache ActiveMQ: com.vordel.jms.apache.activemq.InitialContextFactory
l JBoss application server: org.jnp.interfaces.NamingContextFactory
Axway API Gateway 7.5.2
Policy Developer Guide 164
4 Messaging
Connection Factory:
Enter the name of the connection factory to use when connecting to the JMS provider. The name of the connection factory is vendor-specific. For example, the connection factory for the JBoss application server is org.jnp.interfaces:javax.jnp. Defaults to connectionFactory for embedded and external ActiveMQ.
IBM WebSphere MQ settings
The following settings are displayed when you select a Service Type of IBM MQ:
Host name:
Enter the host name of the JMS provider (for example, localhost).
Port number:
Enter the port number of the JMS provider (for example, 1414).
Queue manager:
Enter the virtual queue manager name by which IBM WebSphere Application Server is known to WebSphere MQ (for example, TEST_BUS).
Channel:
Enter the IBM WebSphere MQ channel name on the WebSphere MQ system (for example, MY_
QM.TO.TEST_BUS).
Initial Context Factory:
The API Gateway uses a connection factory to create a connection with a JMS provider. A connection factory encapsulates a set of connection configuration parameters that have been defined by the administrator. Defaults to com.vordel.jms.ibm.mq.InitialContextFactory. Connection Factory:
Enter the name of the connection factory to use when connecting to the JMS provider. Defaults to connectionFactory.
Settings for all service types
The following optional settings are common to all service types:
Username:
If a user name is required to connect to this JMS provider, enter it here.
Password:
Enter the password for this user.
Custom Message Properties:
You can add JNDI context settings by clicking Add, and entering name and value properties in the fields.
Axway API Gateway 7.5.2
Policy Developer Guide 165
4 Messaging
For the Embedded Apache ActiveMQ service type, you can define Apache ActiveMQ URI parameters using JNDI properties. For example, see the following:
l http://activemq.apache.org/tcp-transport-reference.html
l http://activemq.apache.org/connection-configuration-uri.html
l http://activemq.apache.org/redelivery-policy.html
l http://activemq.apache.org/ssl-transport-reference.html
l http://activemq.apache.org/what-is-the-prefetch-limit-for.html
Configure advanced settings
You can configure the following options on the Advanced Settings tab:
JMS service settings
The advanced JMS service settings are as follows:
JMS Client ID:
Enter the client ID required by JMS durable topic subscriptions to consume messages from the service. For more details, see the following:
l Configure a JMS consumer on page 169
l Read from JMS on page 176
Automatic reconnection:
Select whether a reconnection to the JMS server is performed when the configured JMS provider raises a connection error. This setting is selected by default.
Start first connection asynchronously:
Select whether the first connection attempt is detached from the API Gateway startup sequence. When this setting is selected, API Gateway starts even if the JMS connection cannot be established.
SSL settings
Note
SSL settings are available only for the IBM MQ and external Apache ActiveMQ JMS service types.
You can configure the following SSL settings:
Cipher suite:
Click the browse button on the right, and select SSL cipher suites from the list of JSSE or IBM cipher suites in the dialog (for example, SSL_RSA_WITH_RC4_128_MD5).
Note
When using an IBM MQ JMS service type, you can select only one SSL cipher suite. For more details, see your IBM WebSphere MQ documentation. When using an Apache
ActiveMQ JMS service type, you can select multiple cipher suites.
Axway API Gateway 7.5.2
Policy Developer Guide 166
4 Messaging
Trusted certificates:
When a cipher suite is selected, you can select SSL trusted certificates and authorities from the list. The selected certificates are used to check the JMS server certificate.
Client certificate (SSL mutual authentication):
Click Client Certificate to select the SSL client certificate and key to use. This setting is required only for SSL mutual authentication.
Next steps
When the JMS service has been configured, you can configure the API Gateway to drop messages on to a queue or topic exposed by this service. You can do this when configuring a policy by selecting the service in the Send to JMS or Read from JMS filters. For more details, see the following:
l Send to JMS on page 172
l Read from JMS on page 176
You can also configure JMS sessions for the newly added JMS service at the API Gateway instance level. For more details, see Configure a JMS session on page 167.
Configure a JMS session
JMS services have JMS sessions, which can be shared by multiple JMS consumers, or used by a single JMS consumer only. To configure a JMS session, right-click an API Gateway instance under the Environment Configuration > Listeners node in the Policy Studio tree, and select Messaging System > Add JMS Session. Alternatively, you can configure a JMS session using Messaging System > JMS Wizard.
Note
You must have first configured a JMS service before you can configure a JMS session. For more details, see Configure a JMS service on page 163.
JMS session configuration
The JMS session settings that are displayed on the Session tab depend on whether you selected Add JMS Session or JMS Wizard.
Add JMS session only
If you selected Messaging System > Add JMS Session, configure the following fields:
Axway API Gateway 7.5.2
Policy Developer Guide 167
4 Messaging
JMS service:
Click the browse button on the right, and select a preconfigured JMS service. To add a service, rightclick JMS Services, and select Add a JMS Service. For more details, see Configure a JMS service on page 163. Listener Count:
Specify the number of listeners permitted for this JMS session. Defaults to 1. If the volume of messages arriving at the queue is more than a single thread can process, you can increase the number of threads listening on the queue by increasing the listener count.
Common configuration
In both cases (Add JMS Session and JMS Wizard), configure the following fields:
Remove message from source:
Select one of the following options from the list:
l Immediately when message is read: Message is removed immediately after it is read. l Lazily which will allow for duplicate message: Message is removed lazily, which allows possible duplicate messages and compatibility with previous versions of API Gateway.
l When policy completes without error: Message is removed if the configured policy completes, either with a succeess or failure. If the configured policy does not complete due to an error, the message is not removed. This option allows possible duplicate messages and compatibility with previous versions of API Gateway. This is the default option. l When policy completes and property below evaluates to true: Message is removed if the message attribute configured in Message removal property evaluates to true. This attribute is set to true by default.
Note
After the configured policy executes, if a message is not removed, it is then rolled back. You may need to configure an error path for the messages to prevent a poison message loop. Message removal property:
Enter the message attribute name used by the When policy completes and selector below
evaluates to true option. Monitoring options
The Traffic Monitor tab enables you to configure traffic monitoring settings for the JMS session. To override the system-level traffic monitoring settings, select Override system-level settings, and configure the relevant options. For more details, see the API Gateway Administrator Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 168
4 Messaging
Next steps
When the JMS session has been configured, you can configure JMS consumers for the newly added JMS session at the API Gateway instance level. For more details, seeConfigure a JMS consumer on page 169.
Configure a JMS consumer
Overview
You can configure multiple JMS consumers under a single JMS session, which share that session. Alternatively, you can configure a single JMS consumer per JMS session. Consumers sharing a JMS session access that session serially. Each consumer blocks until a response (if any) is received. Consumers with their own session do not encounter this problem, which may improve performance.
You can configure JMS consumers using the JMS Wizard, or by right-clicking an existing JMS session, and selecting Add JMS Consumer.
Note
You must first configure a JMS service and a JMS session before you can configure a JMS consumer. For more details see Configure a JMS service on page 163.
JMS Message source
On the General tab, configure the following fields in the Message source section:
Source type:
Select one of the following from the list: l Queue
l Topic
l JNDI lookup
Defaults to Queue.
Source Name:
Enter the name of the JMS queue, JMS topic, or JNDI lookup to specify where you want read the messages from. Selector:
Enter an SQL selector expression that specifies a response message. The expression entered specifies the messages that the consumer is interested in receiving. By using a selector, the task of filtering the messages is performed by the JMS provider instead of by the consumer. Axway API Gateway 7.5.2
Policy Developer Guide 169
4 Messaging
The selector is a string that specifies an expression whose syntax is based on the SQL92 conditional expression syntax. The API Gateway instance only receives messages whose headers and properties match the selector. For example, the following expression gets the selected message from the queue:
JMSCorrelationID='${params.query.id}'
JMS consumer type
The JMS consumer type settings enable you to configure the following:
Durable subscription:
Select this setting to use a durable topic subscription to consume messages from the server. This option is available only for Topic and JNDI lookup source types.
Topic subscriber name:
Enter the JMS subscriber name used to identify the durable subscription.
Note
The JMS service used must have a JMS Client ID configured. If a JNDI lookup source is configured, the name must not point to a topic.
Only one durable subscriber (described by the JMS client ID and subscriber name) can be active at a time. Message processing
The Message processing settings include the following:
Extraction Method:
Specify how to extract the data from the JMS message from the drop-down list:
l Create a content.body attribute based on the SOAP over JMS draft specification (the default)
l Insert the JMS message directly into the attribute named below
l Populate the attribute below with the value inferred from message type to Java
Attribute Name:
The name of the API Gateway message attribute that holds the data extracted from the JMS message. Defaults to the jms.message message attribute. Policy:
Select the appropriate policy from the list to run on the JMS message after it has been consumed by the API Gateway. This setting is required.
Send Response to Configured Destination:
Specifies whether the API Gateway sends a reply to the response queue named in the incoming Axway API Gateway 7.5.2
Policy Developer Guide 170
4 Messaging
message (in the ReplyTo header). This option is selected by default. Deselecting this option means that the API Gateway never sends a reply to the response queue named in the ReplyTo header. Logging settings
The Logging Settings tab enables you to configure the logging level for all filters in policies executed on this JMS consumer, and to configure when message payloads are logged.
Transaction Audit Logging Level
You can configure the following settings on all filters executed on the JMS consumer:
Logging
level
Description
Fatal
Logs Fatal log points that occur on all filters executed. Failure
Logs Failure log points that occur on all filters executed. This is the default logging level.
Success
Logs Success log points that occur on all filters executed. For details on logging levels, and configuring logging for a filter, see Set transaction log level and log message on page 758.
Transaction Audit Payload Logging
You can configure the following settings this JMS consumer:
Payload logging
Description
On receive request
from client
Log the message payload when a request arrives from the client. On send response to
client
Log the message payload before the response is sent back to the client.
On send request to
remote server
Log the message payload before the request is sent using any Connection or Connect to URL filters deployed in policies.
On receive response
from remote server
Log the message payload when the response is received using any Connection or Connect to URL filters deployed in a policies.
Axway API Gateway 7.5.2
Policy Developer Guide 171
4 Messaging
For details on how to log message payloads at any point in a specific policy, see Log message payload on page 747.
Send to JMS
Overview
The Send to JMS filter enables you to configure a JMS messaging system to which the API Gateway sends messages. You can configure various settings for the message request and response (for example, destination and message type, how the message system should respond, and so on).
API Gateway provides all the required third-party JAR files for IBM WebSphere MQ and Apache ActiveMQ (both embedded and external).
Note
For other third-party JMS providers only, you must add the required third-party JAR files to the API Gateway classpath for messaging to function correctly. If the provider's implementation is platform-specific, copy the provider JAR files to INSTALL_
DIR/ext/PLATFORM .
INSTALL_DIR is your API Gateway installation, and PLATFORM is the platform on which API Gateway is installed ( Win32, Linux.i386, or SunOS.sun4u-32). If the provider implementation is platform-independent, copy the JAR files to INSTALL_
DIR/ext/lib.
Request settings
The Request tab specifies the following properties of the request sent to the messaging system:
JMS Service:
Click the browse button on the right, and select an existing JMS service in the tree. To add a JMS Service, right-click the JMS Services tree node, and select Add a JMS Service. Alternatively, you can configure JMS services under the Environment Configuration > External Connections node in the Policy Studio tree. For more details, see Configure messaging services on page 161.
Destination type:
Select one of the following from the list: l Queue
l Topic
l JNDI lookup
Defaults to Queue.
Destination:
Enter the name of the JMS queue, JMS topic, or JNDI lookup to specify where you want to drop the messages. Axway API Gateway 7.5.2
Policy Developer Guide 172
4 Messaging
Delivery Mode:
Select one of the following delivery modes:
l Persistent:
Instructs the JMS provider to ensure that a message is not lost in transit if the JMS provider fails. A message sent with this delivery mode is logged to persistent storage when it is sent. This is the default mode.
l Non-persistent:
Does not require the JMS provider to store the message. With this mode, the message may be lost if the JMS provider fails.
Priority Level:
You can use message priority levels to instruct the JMS provider to deliver urgent messages first. The ten levels of priority range from 0 (lowest) to 9 (highest). If you do not specify a priority level, the default level is 4. A JMS provider tries to deliver higher priority messages before lower priority ones but does not have to deliver messages in exact order of priority. Time to Live:
By default, a message never expires. However, if a message becomes obsolete after a certain period, you may want to set an expiry time (in milliseconds). The default value is 0, which means the message never expires. Message ID:
Enter an identifier to be used as the unique identifier for the message. By default, the unique identifier is the ID assigned to the message by API Gateway ( ${id}). However, you can use a proprietary correlation system, perhaps using MIME message IDs instead of API Gateway message IDs. Correlation ID:
Enter an identifier for the message that API Gateway uses to correlate response messages with the corresponding request messages. Usually, if ${id} is specified in the Message ID field above, it is also used here to correlate request messages with their correct response messages. Message Type:
This list enables you to specify the type of data to be serialized and sent in the JMS message to the JMS provider. The option selected depends on what part of the message you want to send to the consumer. For example, to send the message body, select the option to format the body according to the rules defined in the SOAP over JMS recommendation. Alternatively, to serialize a list of namevalue pairs to the JMS message, choose the option to create a MapMessage. Select one of the following serialization options:
l Use content.body attribute to create a message in the format specified in the SOAP
over Java Message Service recommendation:
If this option is selected, messages are formatted according to the SOAP over JMS recommendation. This is the default option because in most cases the message body is routed to the messaging system. When this option is selected, a javax.jms.BytesMessage is created and a JMS property containing the content type text/xml) is set on the message. Axway API Gateway 7.5.2
Policy Developer Guide 173
4 Messaging
l Create a MapMessage from the java.lang.Map in the attribute named below:
Select this option to create a javax.jms.MapMessage from the API Gateway message attribute named below that consists of name-value pairs.
l Create a BytesMessage from the attribute named below:
Select this option to create a javax.jms.BytesMessage from the API Gateway message attribute named below.
l Create an ObjectMessage from the java.lang.Serializable in the attribute named
below:
Select this option to create a javax.jms.ObjectMessage from the API Gateway message attribute named below.
l Create a TextMessage from the attribute named below:
Select this option to create a javax.jms.TextMessage from the message attribute named below.
l Use the javax.jms.Message stored in the attribute named below:
If a javax.jms.Message has already been stored in a message attribute, select this option, and enter the name of the attribute in the field below.
Attribute Name:
Enter the name of the API Gateway message attribute that holds the data that is to be serialized to a JMS message and sent over the wire to the JMS provider. The type of the attribute named here must correspond to that selected in the Message Type field above. Custom Message Properties:
You can set custom properties for messages in addition to those provided by the header fields. Custom properties may be required to provide compatibility with other messaging systems. You can use message attribute selectors as property values. For example, you can create a property called AuthNUser , and set its value to ${authenticated.subject.id}. Other applications can then filter on this property (for example, only consume messages where AuthNUser equals admin). To add a new property, click Add, and enter a name and value in the fields provided on the Properties dialog.
Use the following policy to change JMS request message:
This setting enables you to customize the JMS message before it is published to a JMS queue or topic. Click the browse button on the right, and select a configured policy in the dialog. The selected policy is then invoked before the JMS request is sent to the queuing system. When the selected policy is invoked, the JMS request message is available on the white board in the jms.outbound.message message attribute. You can therefore call JMS API methods to manipulate the JMS request further. For example, you could configure a policy containing a Scripting Language filter that runs a script such as the following against the JMS message:
function invoke(msg) {
var jmsMsg = msg.get("jms.outbound.message");
jmsMsg.setIntProperty("My_JMS_Report", 123);
return true;
}
Axway API Gateway 7.5.2
Policy Developer Guide 174
4 Messaging
Response settings
The Response tab specifies whether API Gateway uses asynchronous or synchronous communication when talking to the messaging system. For example, to use asynchronous communication, you can select the Do not set response option. If synchronous communication is required, you can select to read the response from a temporary queue or from a named queue or topic.
You can also specify whether API Gateway waits on a response message from a queue or topic from the messaging system. API Gateway sets the JMSReplyTo property on each message that it sends. The value of the JMSReplyTo property is the temporary queue, queue, or topic selected in this dialog. It is the responsibility of the application that consumes the message from the queue (JMS consumer) to send the message back to the destination specified in JMSReplyTo. API Gateway sets the JMSCorrelationID property to the value of the Correlation ID field on the Request tab to correlate requests messages to their corresponding response messages. If you select to use a temporary queue or temporary topic, this is created when API Gateway starts up.
Configure how messaging system should respond:
Select where the response message is to be placed using one of the following options:
l Do not set response:
Select this option if you do not expect or do not care about receiving a response from the JMS provider.
l Use temporary queue:
Select this option to instruct the JMS provider to place the response message on a temporary queue. In this case, the temporary queue is created when API Gateway starts up. Only API Gateway can read from the temporary queue, but any application can write to it. API Gateway uses the value of the JMSReplyTo header to indicate the location where it reads responses from.
l Use queue:
If you want the JMS provider to place response messages on a queue, select this option, and enter the queue name in the text box. This is used in the JMSReplyTo field of the response message.
l Use topic:
If you want the JMS provider to place response messages on a topic, select this option, and enter the topic name in the text box. This is used in the JMSReplyTo field of the response message.
l Use named queue or topic (JNDI):
If you want the JMS provider to place response messages on a named queue or topic using JNDI lookup, select this option, and enter the JNDI name for the queue or topic in the text box. This is used in the JMSReplyTo field of the response message.
Wait for response:
If Do not set response is not selected, you can select whether API Gateway waits to receive a response:
Axway API Gateway 7.5.2
Policy Developer Guide 175
4 Messaging
l Wait with timeout (ms):
API Gateway waits a specific time period to receive a response before it times out. If API Gateway times out waiting for a response, the Send to JMS filter fails. Enter the timeout value in milliseconds. The default value of 10000 means that API Gateway waits for a response for 10 seconds. The accepted range of values is 10000 – 20000 ms.
l Selector for response:
If Wait with timeout (ms) is selected, you can enter an SQL selector expression that specifies a response message. The expression entered specifies the messages that the consumer is interested in receiving. By using a selector, the task of filtering the messages is performed by the JMS provider instead of by the consumer.
The selector is a string that specifies an expression whose syntax is based on the SQL92 conditional expression syntax. The API Gateway instance only receives messages whose headers and properties match the selector. For example:
JMSCorrelationID='${params.query.id}'
Note
The JMS consumer automatically returns the results of the invoked policy to the JMS destination specified in the JMSReplyTo header in the request. This means that you do not need to send a reply using the Send to JMS filter.
If the incoming JMS message contains a JMSReplyTo header, the queue or topic expects a response. So when the JMS consumer policy completes, API Gateway sends a message to the JMSReplyTo source in reverse. For example, the consumer reads the JMS message, and populates an attribute with a value inferred from the message type to Java (for example, from TextMessage to String ). When the policy completes, the consumer looks up this attribute and infers the JMS response message type based on the object type stored in the message.
Read from JMS
Overview
The Read from JMS filter enables you to configure a JMS messaging system from which the API Gateway reads messages. You can configure various settings for the JMS message source, message type, and processing options.
API Gateway provides all the required third-party JAR files for IBM WebSphere MQ and Apache ActiveMQ (both embedded and external).
Note
For other third-party JMS providers only, you must add the required third-party JAR files to the API Gateway classpath for messaging to function correctly. If the provider's implementation is platform-specific, copy the provider JAR files to INSTALL_
DIR/ext/PLATFORM .
INSTALL_DIR is your API Gateway installation, and PLATFORM is the platform on Axway API Gateway 7.5.2
Policy Developer Guide 176
4 Messaging
which API Gateway is installed ( Win32, Linux.i386, or SunOS.sun4u-32). If the provider implementation is platform-independent, copy the JAR files to INSTALL_
DIR/ext/lib.
Message source
The Message source settings enable you to configure the following:
JMS Service:
Click the browse button on the right, and select an existing JMS service in the tree. To add a JMS Service, right-click the JMS Services tree node, and select Add a JMS Service . Alternatively, you can configure JMS services under the Environment Configuration > External
Connections node in the Policy Studio tree. For more details, see Configure messaging services on page 161.
Source type:
Select one of the following from the list: l Queue
l Topic
l JNDI lookup
Defaults to Queue.
Source Name:
Enter the name of the JMS queue, JMS topic, or JNDI lookup to specify where you want read the messages from. Selector:
Enter an SQL selector expression that specifies a response message. The expression entered specifies the messages that the consumer is interested in receiving. By using a selector, the task of filtering the messages is performed by the JMS provider instead of by the consumer. The selector is a string that specifies an expression whose syntax is based on the SQL92 conditional expression syntax. The API Gateway instance only receives messages whose headers and properties match the selector. For example, the following expression gets the selected message from the queue:
JMSCorrelationID='${params.query.id}'
Read timeout (ms):
Enter the timeout after which the Read from JMS filter fails. The accepted range of values is 1–
20000 ms. Defaults to 1000 ms.
JMS consumer type
The JMS consumer type settings enable you to configure the following:
Axway API Gateway 7.5.2
Policy Developer Guide 177
4 Messaging
Durable subscription:
Create or use a durable topic subscription to consume messages from the server. This option is only available for Topic and JNDI lookup source types. Note
This is only available with a Topic source and the JMS service used must have a client ID configured. If a JNDI lookup source is configured, the name must not point to a topic. Topic subscriber name:
Enter the JMS subscriber name used to identify the durable subscription.
Message processing
The JMS consumer type settings enable you to configure the following:
Extraction Method:
Specify how to extract the data from the JMS message from the list:
l Insert the JMS message directly into the attribute named below (this is the default)
l Populate the attribute below with the value inferred from message type to Java
Attribute Name:
The name of the API Gateway message attribute that holds the data extracted from the JMS message. Defaults to the jms.message message attribute. Policy:
Select the appropriate policy to run on the JMS message after it has been consumed by the API Gateway.
Send Response to Configured Destination:
Specifies whether the API Gateway sends a reply to the response queue named in the incoming message (in the ReplyTo header). This option is selected by default. Deselecting this option means that the API Gateway never sends a reply to the response queue named in the ReplyTo header. Axway API Gateway 7.5.2
Policy Developer Guide 178
General configuration
5
This section describes some general configuration settings for API Gateway.
Manage Policy Studio projects
179
Manage API Gateway connections
182
Global configuration
184
Policy Studio preferences
190
Policy Studio viewing options
196
Import API Gateway configuration fragment
197
Export API Gateway configuration
200
Compliance validation tools
202
Upgrade log analysis
203
Oracle Security Service Module settings (10g)
211
Kerberos configuration
214
Manage Policy Studio projects
Overview
This topic explains how work with Policy Studio projects when developing API Gateway policies and configuration. For example, this includes basic tasks such as creating, opening, saving, and closing projects. It also includes tasks such as deploying, importing, and exporting configuration from a project, changing a project passphrase, and adding APIs and web services to a project.
Create a new project
To create a new project in Policy Studio, select File > New Project from the main menu, or click New Project on the welcome page. Follow the steps in the New Project wizard.
For more details, see Create a Policy Studio project on page 48.
Open an existing project
To open an existing project in Policy Studio, select File > Open Project from the main menu, or click Open Project on the welcome page, and enter the project details in the dialog. Alternatively, click a link to the existing project in the Recent Projects pane on the welcome page.
Axway API Gateway 7.5.2
Policy Developer Guide 179
5 General configuration
For more details, see Manage API Gateway connections on page 182.
Save changes to a project
When a project is loaded in Policy Studio, you can select File > Save from the main menu to save the changes to the current configuration editor.
Alternatively, select File > Save All to save the changes to all open unsaved configuration editors.
Deploy changes to a project
When a project is loaded in Policy Studio, you can select Tasks > Deploy from the main menu to deploy saved changes to a running API Gateway instance at any time. Alternatively, click the Deploy button in the toolbar. For more details, see Deploy API Gateway configuration on page 219.
Add an API to a project
When a project is loaded in Policy Studio, you can select Tasks > Add REST API from the main menu to add an API to the project. For more details, see Develop REST APIs in Policy Studio on page 131.
Virtualize a web service
When a project is loaded in Policy Studio, you can select Tasks > Virtualize a Service from the main menu to use the API Gateway to virtualize a web service. For more details, see Register and secure web services on page 84.
Change the project passphrase
When a project is loaded in Policy Studio, you can select Tasks > Change Project Passphrase from the main menu to change the encryption passphrase for the API Gateway configuration.
Complete the following fields on the Change Project Passphrase dialog:
l Old Passphrase:
Enter the old encryption passphrase that you wish to change. Alternatively, leave this field blank if you are setting the passphrase for the first time. l New Passphrase:
Enter the new encryption passphrase.
l Confirm New Passphrase: Re-enter the new encryption passphrase to confirm it.
Axway API Gateway 7.5.2
Policy Developer Guide 180
5 General configuration
Note
It is important to distinguish between the p assphrase used by a project on the local file system and the passphrase used by an API Gateway group configuration on a running API Gateway instance. For details on specifying a different passphrase for runtime, see Deploy API Gateway configuration on page 219. For more details on configuring encryption passphrases, see the API Gateway Administrator Guide.
Export configuration packages
When a project is loaded in Policy Studio, you call select File > Export to save the project as a configuration package. Select one of the following from the menu: l Deployment package:
Saves the project as a .fed file that contains all API Gateway configuration. This includes policies, listeners, external connections, users, certificates, and environment settings.
l Policy package:
Saves the project as a .pol file that contains users, certificates, and environment settings. l Environment package:
Saves the project as a .env file that contains policies, listeners, external connections, and environment settings. When you have saved a configuration package, you can use it to create a Policy Studio project in another environment. For more details, see Create a Policy Studio project on page 48.
For more details on configuration packages to promote configuration between environments, see the API Gateway DevOps Deployment Guide.
Import configuration into a project
When a project is loaded in Policy Studio, you can select File > Import > Configuration
Fragment from the main menu to import configuration into the project. This feature enables you to import XML-based configuration previously exported from Policy Studio. For more details, see Import API Gateway configuration fragment on page 197.
You can also select File > Import > Custom filters to import custom filters to be added to the Policy Studio filter palette. For more details, see the API Gateway Developer Guide.
Manage multiple projects
You can work with multiple projects in Policy Studio. When a project is loaded in Policy Studio, you can click the Show List icon (>>) in the toolbar to display a list of currently open views (for example, other open projects and the welcome page). Select an item in the list to switch between views. The toolbar also displays the number of available views beside the Show List icon in the toolbar.
Axway API Gateway 7.5.2
Policy Developer Guide 181
5 General configuration
Close a project
To close the p roject currently open in Policy Studio, select File > Close Project from the main menu. Alternatively, click the X icon next to the project name in the toolbar.
Manage API Gateway connections
Overview
You can use Policy Studio to manage API Gateway server instances. You can open a server connection when creating an p roject based on an API Gateway instance, when opening an existing project, or when deploying a configuration.
Create a new project based on an API Gateway
instance
When you select File > New Project to create a new project, you can select to use an API Gateway instance as the starting point for the project configuration. For details on configuring the server connection for the new project, see Create a Policy Studio project on page 48.
Note
You must first create an API Gateway project before you can connect to a server.
Open an existing project
You can open an existing project using File > Open Project in the main menu, or by clicking Open Project on the welcome page or clicking a link to the existing project in the Recent
Projects pane.
When you select File > Open Project or click Open Project on the welcome page, you can configure the following connection settings in the Open project window:
Location:
Enter or browse to the full path to the project in the file system (for example, C:\Users\john\apiprojects\my_test_project). You can select from the connection history of existing projects in the list.
Project Name:
If a valid project location is selected, Policy Studio completes this field with the project name configured in the .project file in the specified project Location.
Passphrase:
Enter the encryption p assphrase if one has been configured. For more details, see Manage Policy Studio projects on page 179.
Axway API Gateway 7.5.2
Policy Developer Guide 182
5 General configuration
Clear History:
Click this button to clear the connection history in the Recent Projects pane on the welcome page. Open a connection when deploying
When you select Deploy in the toolbar to deploy updated API Gateway configuration to a server, you must first open the server connection. For details on configuring the server connection when deploying, see Deploy API Gateway configuration on page 219.
Note
You must first create an API Gateway project before you can deploy configuration.
Unlock a server connection
You can also unlock an existing connection to a server. This is for emergency use if you have changed configuration, and this results in you being locked out from the Management Services on port 8090. In this case, you have incorrectly configured the authentication filter in the Protect
Management Interfaces policy. For example, if you created and deployed an LDAP connection without specifying the correct associated user accounts, and are now unable to connect to the Admin Node Manager. To unlock a server connection, perform the following steps:
1. Download all the files in the server's conf/fed directory to the machine on which Policy Studio is installed.
2. Start Policy Studio.
3. Create a new project from existing configuration based on the conf/fed directory that you downloaded from the server in step 1 (for details, see Create a Policy Studio project on page 48).
4. Change the configuration details as required (for example, specify the correct user account details for the LDAP connection under the Environment Configuration > External
Connections node).
5. Upload the files back to the server's conf/fed directory.
6. Restart the Admin Node Manager.
For more details on Management Services, see Configure HTTP services on page 290.
Axway API Gateway 7.5.2
Policy Developer Guide 183
5 General configuration
Global configuration
Overview
For convenience, Policy Studio displays various global configuration options. For example, it includes libraries of users, X.509 certificates, and schemas that can be added globally and then referenced in filters and policies. This avoids the need to reconfigure details over and over again (for example, each time a schema or certificate is used). The following global configuration options are available in Policy Studio, each of which are discussed briefly in the sections below:
l API Gateway settings on page 184
l Web service repository on page 185
l API Gateway instances on page 185
l Policies on page 186
l Certificates and keys on page 186
l API Gateway user store on page 186
l System alerts on page 187
l External connections on page 187
l Caches on page 188
l Black list and White list on page 188
l WSDL and XML schema document bundles on page 189
l Scripts on page 189
l Stylesheets on page 189
l References on page 190
API Gateway settings
You can configure the underlying configuration settings for API Gateway using the Environment
Configuration > Server Settings node in the Policy Studio tree. This includes the following settings:
l API Manager
l General
l Logging
l Messaging
l Monitoring
l Security
Axway API Gateway 7.5.2
Policy Developer Guide 184
5 General configuration
For more details, see the API Gateway Administrator Guide.
Web service repository
The easiest way to secure a web service with API Gateway is to import the Web Services Description Language (WSDL) file for the service using Policy Studio. This creates a Service Handler for the web service, which is used to control and validate requests to the web service and responses from the web service. The WSDL file is also added to the web service repository, making sure to update the URL of the web service to point at the machine on which API Gateway is running instead of that on which the web service is running. Consumers of the web service can then query API Gateway for the WSDL file for the web service. The consumer then knows to route messages to API Gateway instead of attempting to route directly to the web service, which most likely is not available on a public IP address.
The web service repository offers a very simple way of securing a web service with minimal impact on consumers of that service. Because of this, the web service repository should be used as the primary method of setting up policies within Policy Studio. For more information on using the repository to register a web service, see Register and secure web services on page 84.
API Gateway instances
A single running instance of API Gateway enables you to configure at least two interfaces: one for public traffic, and a second for listening for and serving configuration data. The configuration interface should rarely need to be updated. However, you might need to add several HTTP interfaces. For example, an HTTP interface and an SSL-enabled HTTPS interface.
Furthermore, you can add features such as the following at the API Gateway instance level:
l Remote hosts to control connection settings to a server
l SMTP interfaces to configure email relay
l File transfer services for FTP, FTPS, and SFTP
l Policy execution schedulers to run policies at regular time intervals
l JMS listeners to listen for JMS messages
l Packet sniffers to inspect packets at the network level for logging and monitoring
l FTP pollers to retrieve files to be processed by polling a remote file server
l Directory scanners to scan messages dumped to the file system
Because API Gateway can read messages from HTTP, SMTP, FTP, JMS, or a directory, this enables it to perform protocol translation. For example, API Gateway can read a message from a JMS queue, and then route it on over HTTP to a web service. Similarly, API Gateway can read XML messages that have been put into a directory on the file system using FTP, and send them to a JMS messaging system, or route them over HTTP to a back-end system.
For more information on configuring API Gateway instances, see Configure API Gateway instances on page 279.
Axway API Gateway 7.5.2
Policy Developer Guide 185
5 General configuration
Policies
A policy is made up of a sequence of modular, reusable message filters, each of which processes the message in a particular way. There are many categories of filters available, including authentication, authorization, content filtering, routing, and many more. For example, a typical policy might contain an authentication filter, followed by several content-based filters (for example, Schema Validation, Threatening Content, Message Size, XML Complexity, and so on), and provided all configured filters run successfully, the message is routed on to the configured destination. A policy can be thought of as a network of message filters. A message can traverse different paths through the network depending on what filters succeed or fail. This enables you to configure policies that, for example, route messages that pass one Schema Validation filter to one back-end system, and route messages that pass a different Schema Validation filter to a different system. You can use policy containers to help manage your policies. These are typically used to group together a number of similar policies (for example, all authentication policies) or to act as an umbrella around several policies that relate to a particular policy (for example, all policies for the getQuote web service). A number of useful policies that ship with API Gateway are found in the Policy Library policy container. This container is prepopulated with policies to return various types of faults to the client and policies to block certain types of threatening content, among others. You can also add your own policies to this container, and create your own policy containers as necessary to suit your own requirements. Certificates and keys
API Gateway must be able to trust X.509 certificates to establish SSL connections with external servers, validate XML Signatures, encrypt XML segments for certain recipients, and for other such cryptographic operations. Similarly, a private key is required to carry out certain other cryptographic operations, such as message signing and decrypting data.
The Certificate Store contains all the certificates and keys that are considered to be trusted by the API Gateway. Certificates can be imported into or created by the certificate store. You can also assign a private key to the public key stored in a certificate, by importing the private key, or by generating one using the provided interface.
For more information on importing and creating certificates and keys, see Manage X.509 certificates and keys on page 230.
API Gateway user store
Users are mainly used for authentication purposes in API Gateway. In this context, the User Store acts as a repository for user information against which users can be authenticated. You can also store user attributes for each user or user group. For example, you can then use these attributes when generating SAML attribute assertions on behalf of the user. Manage API Gateway users on page 243 contains more details on how to create users, user groups, and attributes. Axway API Gateway 7.5.2
Policy Developer Guide 186
5 General configuration
System alerts
API Gateway can send system alerts to various error reporting systems in the case of a policy error (for example, when a request is blocked by a policy). For more details on how to configure API Gateway to send these alerts, and for details of all of the alert destinations that you can configure, see Configure system alerts on page 245. Note
Not all alert destinations are available on the API Gateway Appliance.
External connections
API Gateway can leverage your existing identity management infrastructure and avoid maintaining separate silos of user information. For example, if you already have a database full of user credentials, API Gateway can authenticate requests against this database, rather than using its own internal user store. Similarly, API Gateway can authorize users, look up user attributes, and validate certificates against third-party identity management servers. You can add each connection to an external system as a global External Connection in Policy Studio so that it can be reused across all filters and policies. For example, if you create a policy that authenticates users against an LDAP directory and then validates an XML signature by retrieving a public key from the same LDAP directory, it makes sense to create a global external connection for that LDAP directory. You can then select the LDAP connection in both the authentication and XML signature verification filters, rather than having to reconfigure it in both filters. For example, you can use the external connections interface to configure global connections such as the following:
l Authentication repository profiles
l Database connections
l ICAP servers
l JMS services
l Kerberos services
l LDAP connections
l Proxy servers
l Radius clients
l SiteMinder connections
l TIBCO connections
l Tivoli connections
l XKMS connections
You can also use external connections to configure a group of related URLs. This is most useful to round-robin between a number of related URLs to ensure high availability. When API Gateway is configured to use a URL Connection Set (instead of just a single URL), it round-robins between the URLs in the set.
Axway API Gateway 7.5.2
Policy Developer Guide 187
5 General configuration
For more information on configuring external connections and connection sets, see External connections on page 371.
Caches
You can configure API Gateway to cache responses from a back-end web service. For example, if API Gateway receives two successive identical requests it can (if configured) take the response for this request from the cache instead of routing the request on to the web service and asking it to generate the response again. As a result, excess traffic is diverted from the web service making it more responsive to requests for other services. API Gateway is saved the processing effort of routing identical requests unnecessarily to the web service, and the client benefits from the far shorter response time. You can configure local caches for each running instance of API Gateway. If you have deployed multiple API Gateways throughout your network, you can configure a distributed cache where cache events on one cache are replicated across all others. For example, if a response message is cached at one instance of API Gateway, it is added to all other caches. For more details on how to configure API Gateway to use local and distributed caches, see Global caches on page 259. Black list and White list
The White list is a global library of regular expressions that can be used across several different filters. For example, the Validate HTTP Headers , Validate Query String , and Validate
Message Attributes filters all use regular expressions from the White list to ensure that various parts of the request contain expected content. The White list is prepopulated with regular expressions that can be used to identify common data formats, such as alphanumeric characters, dates, email addresses, IP addresses, and so on. For example, if a particular HTTP header is expected to contain an email address, the Email Address expression from the library can be run against the HTTP header to ensure that it contains an email address as expected. This is yet another way that the API Gateway can ensure that only the correct data reaches the web service. While the White list contains regular expressions to identify valid data, the Black list contains regular expressions that are used to identify common attack signatures. For example, this includes expressions to scan for SQL injection attacks, buffer overflow attacks, ASCII control characters, DTD entity expansion attacks, and many more. You can run various parts of the request message against the regular expressions contained in the Black list library. For example, the HTTP headers, request query string, and message (MIME) parts can be scanned for SQL injection attacks by selecting the SQL-type expressions from the Black list .The Threatening Content filter also uses regular expressions from the Black list to identify attack signatures in request messages. For more details on running regular expressions, see the following topics:
Axway API Gateway 7.5.2
Policy Developer Guide 188
5 General configuration
l HTTP header validation on page 617
l Query string validation on page 620
l Validate selector expression on page 628
l Threatening content on page 612
WSDL and XML schema document bundles
The WSDL documents and XML schemas that API Gateway can use to validate incoming requests against are stored in a global cache. The Schema Validation filter validates the format of an incoming message against a schema from the cache. This ensures that only messages of the correct format are processed by the target system. In the Policy Studio navigation tree, you can access the global cache of WSDL documents or XML schema documents by selecting Resources > WSDL Document Bundles or Resources > XML
Schema Document Bundles. Select a child node to view its contents. To add a schema, rightclick the XML Schema Document Bundles node, and select Add Schema. For more details on adding XML schemas to the cache see Manage WSDL and XML schema documents on page 107.
When you have imported your XML schemas, see Schema validation on page 605 for instructions on how to validate XML messages against the schemas in the cache.
Scripts
The Scripts library contains the JavaScript and Groovy scripts that API Gateway can use to interact with the message as it is processed. For example, you use these scripts with the Scripting Filter to get, set, and evaluate specific message attributes.
In the Policy Studio navigation tree, you can access the global scripts library by selecting Resources > Scripts. Select a child node to view or edit its contents. To add a script, right-click the Scripts node, and select Add Script. For more details on using the Scripts Library dialog to add scripts, and on configuring API Gateway to use scripts, see Scripting language filter on page 858. Stylesheets
The Stylesheets library contains the XSLT style sheets that API Gateway can use to transform incoming request messages. The XSLT Transformation filter enables you convert the contents of a message using these style sheets. For example, an incoming XML message that adheres to a specific XML schema can be converted to an XML message that adheres to a different schema before it is sent to the destination web service. In the Policy Studio navigation tree, you can access the global style sheet library by selecting Resources > Stylesheets. Select a child node to view or edit its contents. To add a style sheet, right-click the Stylesheets node, and select Add Stylesheet. Axway API Gateway 7.5.2
Policy Developer Guide 189
5 General configuration
For more details on using the Stylesheet Library dialog to add style sheets, and on configuring API Gateway to use XSLT style sheets, see Transform with XSLT on page 666. References
References can occur between API Gateway configurations items (for example, a policy might include a reference to an external connection to a database). You can view references between configuration items in Policy Studio by right-clicking an item, and selecting Show All
References. References are displayed in a tab at the bottom of the window. The Show All References option is enabled only for items that have references to other items. For an example in a default API Gateway installation, right-click Environment Configuration > External Connections > LDAP Connections > Sample Active Directory Connection , and select Show all References. Showing all references is useful for impact analysis (for example, before upgrading or migrating), and is a general navigation aid. Policy Studio preferences
Overview
The Preferences dialog enables you to configure a range of options for the Policy Studio. For example, you can configure the level at which the Policy Studio traces diagnostic output, customize the look-and-feel of the Policy Studio, or configure the timeout for the Policy Studio connection to the API Gateway. Each of the available settings is discussed in the following sections.
Note
When finished your updates, remember to click Apply at the bottom of the window, and to click Deploy in the toolbar. Environmentalization
Environmentalization refers to configuring environment-specific settings for a particular target environment (for example, users, certificates, and external connections for a development environment). You can enable Policy Studio to display settings that have been environmentalized by selecting the Allow environmentalization of fields option. When this option is selected, you can environmentalize a selected field (for example, database URL) by clicking the globe icon to the right of the field. Alternatively, press Ctrl-E. When you have selected settings to be environmentalized, the field is disabled, and the globe icon is displayed on the right. You can manage settings that have been environmentalized under the Environment
Settings node in the Policy Studio tree. For more details, see the API Gateway DevOps Deployment Guide. Axway API Gateway 7.5.2
Policy Developer Guide 190
5 General configuration
FIPS mode
The FIPS Mode setting enables you to enable Federal Information Processing Standards (FIPS) mode for Policy Studio. This enables FIPS-certified cryptographic modules and ensures that all cryptographic operations (for example, SSL) are performed by these modules. To enable FIPS mode, select Enable FIPS mode in Axway Policy Studio. Note
To run in this mode, you must install API Gateway with a FIPS-compliant mode license.
For more details on FIPS, see the API Gateway Security Guide.
Map graphical editor
These settings enable you to customize the look and feel of the Data Map Editor when creating mappings graphically in Policy Studio. For more information, see Manage data maps on page 117.
Associations are the connections or links between a source element and a target element in a mapping. You can change the colors of the association containers and the association lines.
You can change the color of the following association containers:
l Associations
l Selected associations
l Disabled associations
You can also change the spacing between containers in the mapping. The default spacing is 7 pixels.
You can change the color of the following association lines:
l Association lines
l Selected association lines
l Association lines for hidden objects
You can also change the insertion position of a new association. Choose from the following options:
l Above the selected line
l Below the selected line
l At the end
Policy colors
The Policy Colors settings enable you to customize the look-and-feel of the Policy Canvas in the Policy Studio. For example, you can change the colors of the following components:
l Policy Background:
Changes the background color of the Policy Canvas.
Axway API Gateway 7.5.2
Policy Developer Guide 191
5 General configuration
l Missing Attribute:
You can right-click the Policy Canvas, and select Show All Attributes from the context menu. When this is selected, each filter displays the list of required and generated message attributes that are relevant for that filter. If a required attribute has not been generated by a previous filter in the policy, the attribute is highlighted in a different color (red by default). You can change this color by selecting an appropriate color using this setting. l Success Path:
You can change the color of the Success Path link using this setting.
l Failure Path:
Similarly, you can change the color of the Failure Path link here.
l Show Link Labels:
If this option is selected, a Success Path is labeled with the letter S, while a Failure Path is labeled F.
Proxy settings
You can specify global proxy settings that apply only when downloading WSDL, XSD, and XSLT files from the Policy Studio. These include the following settings:
Proxy Setting
Description
Host
Host name or IP address of the proxy server.
Port
Port number on which to connect to the proxy server.
Username
Optional user name when connecting to the proxy server.
Password
Optional password when connecting to the proxy server.
You can also specify individual proxy servers under the Environment Configuration > External
Connections node in the Policy Studio tree. These are different from the global proxy settings in the Preferences because you can specify these proxy servers at the filter level (in the Connection and Connect To URL filters). For more details, see Configure proxy servers on page 421.
Runtime dependencies
The Runtime Dependencies setting enables you to add JAR files to the Policy Studio classpath. For example, if you write a custom API Gateway filter, you must add its JAR file, and any third-party JAR files that it uses, to the Runtime Dependencies list.
Click Add to select a JAR file to add to the list of dependencies, and click Apply when finished. A copy of the JAR file is added to the plugins directory in your Policy Studio installation. Note
You must restart Policy Studio and the server for these changes to take effect. You should restart Policy Studio using the policystudio -clean command.
Axway API Gateway 7.5.2
Policy Developer Guide 192
5 General configuration
Custom filter dependencies
If your custom filter introduces a dependency on a new third-party library, you must first check if the required library is already available under the following directory and sub-directories:
INSTALL_DIR/apigateway/system/lib
Note
Any JAR file that you add under the following directories will be pushed ahead of apigateway/system JAR files on the CLASSPATH:
l INSTALL_DIR/apigateway/ext/lib
l INSTALL_DIR/apigateway/groups/GROUP_ID/INSTANCE_ID/ext/lib
For example, API Gateway ships with specific versions of several Apache Commons JARs. Introducing conflicting versions of these JARs could adversely affect the ability of the API Gateway and Node Manager to function correctly.
SSL settings
The SSL Settings enable you to specify what action is taken when an unrecognized server certificate is presented to the client. This allows the Policy Studio to connect to SSL services without a requirement to add a certificate to its JVM certificate store. Configure one of the following options:
Prompt
User
When you try to connect to SSL services, you are prompted with a dialog. If you choose to trust this particular server certificate displayed in the dialog, it is stored locally, and you are not prompted again. Trust All
All server certificates are trusted.
Keystore
Enter or browse to the location of the Keystore that contains the authentication credentials sent to a remote host for mutual SSL, and enter the appropriate Keystore Password.
Status bar
The Show Status Bar setting enables you to specify whether the applications status bar is displayed at the bottom of the Policy Studio screen. For example, this status bar displays details such as the currently selected tree node on the left, and details such as the heap size on the right. You can also use the status bar to run garbage collection by clicking the trash icon on the right. This status bar is enabled by default.
Axway API Gateway 7.5.2
Policy Developer Guide 193
5 General configuration
Trace level
You can set the level at which the Policy Studio logs diagnostic output by selecting the appropriate level from the Tracing Level drop-down list. Diagnostic output is written to a file in the /logs directory of your Policy Studio installation. You can select Window > Show View > Console in the main menu to view the trace output in the Console window at the bottom of the screen. The default trace level is INFO.
You can also configure the Maximum number of files output to the /logs directory. Defaults to 10 files.
WS-I settings
Before importing a WSDL file that contains the definition of a web service into the web service repository, you can test the WSDL file for compliance with the Web Service Interoperability (WS-I) Basic Profile. The WS-I Basic Profile contains a number of Test Assertions that describe rules for writing WSDL files for maximum interoperability with other WSDL authors, consumers, and other related tools. The WS-I settings are described as follows:
WS-I
Setting
Description
WS-I Tool
Location
Use the Browse button to specify the full path to the Java version of the WSInteroperability testing tools (for example, C:\Program Files\WSI_
Test_Java_Final_1.1\wsi-test-tools).The WS-I testing tools are used to check a WSDL file for WS-I compliance. You can download them from www.ws-i.org. Results
Type
Select the type of WS-I test results that you wish to view in the generated report from the drop-down list. You can select from all, onlyFailed, notPassed, or notInfo.
Message
Entry
Specify whether message entries should be included in the report using the check box (selected by default).
Failure
Message
Specify whether the failure message defined for each test assertion should be included in the report using the check box (selected by default).
Assertion
Description
Specify whether the description of each test assertion should be included in the report using the check box (unselected by default).
Verbose
Output
Specify whether verbose output is displayed in the Policy Studio console window using the check box (unselected by default). To view the console window, select Window > Show Console from the Policy Studio main menu. Axway API Gateway 7.5.2
Policy Developer Guide 194
5 General configuration
Note
On Linux/UNIX, when you download WS-I Testing Tools v1.1, you must run dos2unix on /java/bin/Analyzer.sh and /java/bin/setenv.sh. This is because both files do not have executable privileges set and have Windows line endings, so the shell interpreter is unable to use them.
For details on running the WS-I testing tools, see Manage WSDL and XML schema documents on page 107.
XML settings
The XML settings enable you to configure a range of options that affect how XML files are treated in the Policy Studio.
XML Files
This includes the following options:
Creating or
saving files
Specifies a line delimiter (for example, Mac, Unix, Windows, or No
Creating files
Specifies a file suffix ( xml), and the type of encoding (for example, ISO
translation).
10646/Unicode(UTF-8)).
Validating files
Configures whether to warn when no grammar is specified.
Source
This includes the following options:
Formatting
Specifies a range of formatting options (for example, line width, line breaks, and indentation).
Content assist
Specifies whether to make suggestions and which strategy to use (for example, Lax or Strict).
Grammar
constraints
Specifies whether to use inferred grammar in the absence of DTD/Schema.
Syntax Coloring
These settings enable you to associate specific colors with specific XML syntax elements (for example, attribute names, comment delimiters, or processing instruction content).
Axway API Gateway 7.5.2
Policy Developer Guide 195
5 General configuration
Policy Studio viewing options
Overview
You can filter the Policy Studio navigation tree on the left of the window to display specified tree nodes only. You can click the Options link at the bottom of the tree to display additional viewing options. These enable you to configure whether management services and tree node configuration types are displayed in the tree. Finally, you can configure how the Policy Studio policy filter palette is displayed on the right of the window when editing policies. Filter the tree
To filter the tree by a specific node name, enter the name in the text box above the tree. When you enter a name (for example, SOAP Schema), the tree is filtered automatically, and all occurrences are displayed in the tree. Filtering the tree is especially useful in cases where many policies have been configured in the Policy Studio, and you wish to find a specific tree node (for example, a schema filter named Check
against SOAP Schema). Configure viewing options
When you click the Options link at the bottom left of the navigation tree, you can configure the following viewing option:
Show Types:
Select this option to show the Type column in the Policy Studio navigation tree. This shows the type of each node in the tree (for example, HTTP Service or Remote Host). This option is not selected by default. When this option is selected, you can use the Filter by type setting.
Configure the policy filter palette
When editing policies, you can configure how the Policy Studio policy filter palette is displayed on the right of the window. Right-click the filter palette, and select from the following options:
Layout:
Specifies how the filters are displayed in each category in the palette. By default, the filters are displayed in a list. Select one of the following options from the context menu:
l Columns
l List
Axway API Gateway 7.5.2
Policy Developer Guide 196
5 General configuration
l Icons Only
l Details
Customize:
The Customize Palette dialog enables you to customize each of the items displayed in the filter palette. Select a node in the tree on the left to display what can be customized on the right. For example, you can edit a filter name and description, specify whether it is hidden, and add tags to help searches. In addition, you can use the buttons above the tree to add or delete new category drawers or separators. You can also move a selected category drawer up or down in the palette.
Settings:
The Palette Settings dialog enables you to customize settings such as fonts, layout, and category drawer options (for example, close each drawer automatically when there is not enough room on the window). Restore Palette Defaults:
Restores all the palette settings from a default API Gateway installation. Import API Gateway configuration fragment
Overview
You can import XML-based configuration data into your API Gateway configuration (for example, policies, certificates, and users). For example, this is useful in a development environment if you wish to share and test configuration with other developers. If you have XML-based configuration data that was previously exported from one API Gateway installation, by importing into another API Gateway installation, you can share API Gateway configuration in a development environment. This also enables you to manage differences and references between configuration components.
For details on exporting configuration data, see Export API Gateway configuration on page 200.
Note
The recommended way to export configuration between different environments is to use configuration packages. Select File > Export from the main menu. For more details, see Manage Policy Studio projects on page 179.
Import configuration fragment
To import previously-exported API Gateway configuration data, perform the following steps:
1. Click the Import Configuration Fragment button in the Policy Studio toolbar.
2. Browse to the location of the XML file that contains the previously exported configuration data that you wish to import.
3. Select the XML file, and click Open.
Axway API Gateway 7.5.2
Policy Developer Guide 197
5 General configuration
4. If a passphrase was set on the configuration from which the data was previously exported, enter it in the Enter Passphrase dialog, and click OK.
5. In the Import Configuration dialog, all configuration items are selected for import by default. If you do not wish to import specific items, deselect them in the tree. For more details, see View differences on page 198.
6. Click OK to import the selected configuration items.
7. The selected configuration items are imported into your API Gateway configuration and displayed in the Policy Studio tree. For example, any imported policies and containers are displayed under the Policies node.
Note
Be careful when deselecting configuration nodes for import. Deselecting certain nodes might make the imported configuration inconsistent by removing supporting configuration. View differences
The Import Configuration dialog displays the differences between the existing stored configuration data (destination) and the configuration data to be imported (source). Differences are displayed in the tree as follows:
Addition
Exists in the source Configuration being imported but not in the destination Configuration. Displayed as a green plus icon. Deletion
Exists in the destination Configuration but not in the source Configuration being imported. Displayed as a red minus icon.
Conflict
Exists in both Configurations but is not the same. Displayed as a yellow warning icon.
If you select a particular node in the Import Configuration tree, the Differences Details panel at the bottom of the screen shows details for this Configuration entity (for example, added or removed fields). In the case of conflicts, changed fields are highlighted. Some Configuration entities also contain references to other entities. In this case, an icon is displayed for the field in the Difference Details panel. If you double-click a row with an icon, you can drill down to view further Difference Details dialogs for those entities. What is imported
When configuration data is imported, some configuration items are imported in their entirety. For example, if the contents of a particular policy are different, the entire policy is replaced (new filters are added, missing filters are removed, and conflicting filters are overwritten). In addition, if a complex filter differs in its children, child items are removed and added as required (for example, WS Filter, Web service, User, and so on). Axway API Gateway 7.5.2
Policy Developer Guide 198
5 General configuration
Other imports are additive only. For example, importing a single certificate does not remove the certificates already in the destination Certificate store. All references to other policies are also maintained during import. Note
Although importing some configuration items removes child items by default, you can deselect child nodes to keep existing child items. However, you should take care to avoid inconsistencies. The default selection applies in most cases.
Upgrade configuration from an earlier version
When you import configuration created using an earlier version of API Gateway, the configuration is automatically upgraded to the current API Gateway version configuration. This results in the migration of the configuration entities present in the .xml file that is being imported.
The Migration Report trace console at the bottom of the window displays the migration report output that is generated when the configuration is upgraded. For example:
The Migration Report console also displays links that navigate to the appropriate upgraded configuration entity. For example, the following window is displayed when the MyFirstDirectoryScanner link is clicked:
For more details on upgrading, see the API Gateway Upgrade Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 199
5 General configuration
Export API Gateway configuration
Overview
You can export API Gateway configuration data by right-clicking a Policy Studio tree node (for example, policy or policy container), and selecting the relevant export menu option (for example, Export Policy). The configuration is exported to an XML file, which you can then import into a different API Gateway configuration. For example, this is useful in a development environment if you wish to share and test configuration with other developers. By exporting configuration data from one API Gateway installation, and importing into another API Gateway installation, you can effectively share your API Gateway configuration in a development environment. This also enables you to manage differences and references between configuration components.
For details on importing configuration data, see Import API Gateway configuration fragment on page 197.
Note
For details on migrating API Gateway configuration between development, testing, and production environments, see the API Gateway DevOps Deployment Guide.
What is exported
You can export API Gateway configuration items by right-clicking a node in the Policy Studio tree. For example, this includes the following Policy Studio tree nodes:
l Policies
l Policy containers
l Schemas
l Alerts
l Caches
l Regular expressions (White list)
l Attacks (Black list)
l Users
l Certificates
l Relative paths
l Remote hosts
l Database connections
In addition, you can also export configuration items that are associated with the selected tree node. For example, this includes referenced policies, MIME types, regular expressions, schemas, and remote hosts. For details on exporting additional configuration items, see the next section. Axway API Gateway 7.5.2
Policy Developer Guide 200
5 General configuration
Export configuration items
To export API Gateway configuration items, perform the following steps:
1. Right-click a Policy Studio tree node (for example, policy or policy container), and select the relevant menu option (for example, Export Policy).
2. The first window in the export wizard is a read-only window that displays the configuration items to be exported. The Exporting tree displays the selected tree node (in this case, policy), which is exported by default. The following configuration items will also be exported tree includes additional referenced items that are also exported by default along with the policy (for example, MIME types, regular expressions, and schemas).
3. You can click Finish if this selection suits your requirements. Otherwise, click Next to refine the selection.
4. In the next window, you can select optional configuration items for export. The Additional
configuration items that may be exported tree on the left includes dependent items that are not exported by default. For example, these include the following:
l Outbound references: Configuration items directly referenced out from the export set to other configuration stores (for example, certificates, users, or external connections).
l Inbound references: Configuration items in other configuration stores that directly reference items in the export set.
l Associated configuration directly related to the export set (for example, remote hosts or relative paths).
5. To add an item for export, select it in the Additional configuration that may be exported tree on the left, and click Add.
6. To remove an item for export, select it in the Additional configuration that will be
exported tree on the right, and click Remove.
Note
The original set of items in the Additional configuration that will be
exported tree cannot be removed. Only items added from the Additional
configuration that may be exported tree can be removed.
7. By default, items displayed in the Additional configuration that may be exported tree are scoped to direct references to the export set (inbound, outbound, and associated). You can select Display additional configuration that depends on items to be exported to recursively add references to this tree when additional configuration items are added to the export set.
8. Click OK to export the selected configuration.
Referenced Policies
When exporting a policy or policy container, by default, any policies referenced by the policy are included for export and displayed in the Additional configuration that will be exported list.
Axway API Gateway 7.5.2
Policy Developer Guide 201
5 General configuration
Compliance validation tools
Overview
Policy Studio contains validation tools for checking the compliance of your configuration against the following security standards:
l Federal Information Processing Standards (FIPS) 140-2 l National Institute of Standards and Technology (NIST) Suite B l National Institute of Standards and Technology (NIST) Suite B Top Secret Validate FIPS compliance
You can run the FIPS Compliance Validation Tool to check that a configuration is FIPS compliant. This tool is available from the Tools > Check Security Constraints > FIPS menu option. When you run the tool, it generates a list of violations, for example:
Click the link for a violation to go to the part of the configuration that is not compliant. For guidance on compliant settings for filters, see the API Gateway Security Guide.
Validate Suite B compliance
You can run the Suite B Compliance Validation Tool to check that a configuration is Suite B compliant. This tool is available from the Tools > Check Security Constraints > SuiteB menu option. When you run the tool, it generates a list of violations. Click the link for a violation to go to the part of the configuration that is not compliant. For guidance on compliant settings for filters, see the API Gateway Security Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 202
5 General configuration
Validate Suite B Top Secret compliance
You can run the Suite B Top Secret Compliance Validation Tool to check that a configuration is Suite B compliant. This tool is available from the Tools > Check Security Constraints >
SuiteBTS menu option. When you run the tool, it generates a list of violations. Click the link for a violation to go to the part of the configuration that is not compliant. For guidance on compliant settings for filters, see the API Gateway Security Guide.
Upgrade log analysis
Policy Studio provides graphical features to help you detect and analyze upgrade issues. You can perform the following in Policy Studio:
l If sysupgrade has identified issues during the upgrade (for example, web service configuration issues), you can use the Tools > Upgrade Log Analysis option in Policy Studio to analyze the upgrade.log file. See Manual upgrade log analysis on page 203.
l If you create a new project in Policy Studio from an existing configuration, or if you import a configuration fragment, an automatic upgrade is triggered and the Upgrade Log Analysis window opens. This allows you to view the log and resolve any issues. See Automatic upgrade log analysis on page 204.
This topic describes both cases with examples of how to resolve critical upgrade issues in Policy Studio.
Manual upgrade log analysis
The sysupgrade upgrade command might generate errors or warnings that need to be resolved in Policy Studio. This includes, for example, issues with web service or REST API configuration, or with OAuth credentials. For more details, see Example critical/major issues and recommended solutions on page 206.
When prompted to perform upgrade log analysis in Policy Studio, perform the following steps:
1. Open the problematic API Gateway configuration in Policy Studio. For example, in Policy Studio version 7.5.2, create a new project using the From existing configuration option, and select the following directory:
Axway-7.5.2/apigateway/upgrade/bin/out/upgrade/esgroups/groups/group2/conf/fed
2. Select Tools > Upgrade Log Analysis from the main menu.
Axway API Gateway 7.5.2
Policy Developer Guide 203
5 General configuration
3. Select the upgrade.log file generated by sysupgrade, for example: Axway-7.5.2/apigateway/upgrade/bin/out/log/upgrade.log
4. Click Open.
5. If the log file contains data on multiple groups, select the group configuration to analyze in the dialog.
Note
The upgrade.log file generated by sysupgrade can contain upgrade information for multiple groups, whereas the automatic upgrades triggered by Policy Studio are specific to the project upgraded.
6. In the Upgrade Log Analysis pane, click View Log. For more details, see Example upgrade log analysis on page 205.
Automatic upgrade log analysis
An automatic upgrade can be triggered in Policy Studio when you create a new API Gateway project from an existing:
l API Gateway configuration package ( .fed, .pol or .env file)
l API Gateway configuration directory
You can also trigger an automatic upgrade by importing an API Gateway configuration fragment (File > Import Configuration Fragment).
In either case, in the Upgrade Log Analysis pane, click View Log. For more details, see Example upgrade log analysis on page 205.
Policy Studio-triggered upgrade logs are stored under the policystudio/trace directory and are prefixed with the project name or configuration fragment name, for example:
l webservice_fragment_upgrade_20160317125324.log
l my_project_upgrade_20160417125319.log
For more details on creating API Gateway projects and importing configuration fragments, see Create a Policy Studio project on page 48 and Import API Gateway configuration fragment on page 197.
Axway API Gateway 7.5.2
Policy Developer Guide 204
5 General configuration
Example upgrade log analysis
When upgrading an earlier version API Gateway configuration to version 7.5.2, the Upgrade Log
Analysis pane on the right lists the upgrade issues that need to be resolved. For example, when upgrading a version 7.3.1 API Gateway configuration, the following example shows an OAuth-specific issue and its recommended solution.
You can click the eraser icon on the left of each issue to mark the issue as complete when it has been resolved.
The following example shows a critical web service issue encountered when upgrading a version 7.2.2 configuration:
Tip
To see this informational window in Policy Studio, hover over an issue.
In this case, the web service could not be upgraded, and has been discarded. You must reimport the WSDL into your new API Gateway7.5.2 installation using Policy Studio. For more details, see Example critical/major issues and recommended solutions on page 206.
Axway API Gateway 7.5.2
Policy Developer Guide 205
5 General configuration
Upgrade indicators in Policy Studio tree
You can view the critical upgrade issues for web services (for example, the Discarded Web
Services, or WSDL files using an Old Repository Format) as text in the Policy Studio tree on the left. If you close the Upgrade Log Analysis view or ignore the issues, the indicator text is no longer displayed.
View more details in upgrade log
To view more details on a specific upgrade issue in the right pane, click View Log to display the relevant entry in the upgrade log file.
Restore completed issues
All completed issues are persisted to disk. This means that you can shut down Policy Studio or the Upgrade Log Analysis view and continue later. To restore completed issues to the view at any time, click Show All Issues in the right pane.
Example critical/major issues and
recommended solutions
This section describes some critical and major upgrade issues displayed by Policy Studio and provides recommended solutions.
Discarded web service
Problem: The WSDL file for the web service could not be upgraded.
Solution: You must re-register the WDSL in the web service repository. Perform the following steps:
1. Copy the original WSDL URL displayed in Policy Studio to the clipboard.
2. Click the Discarded web service hyperlink to locate the web service group it was originally registered in.
3. On that web service group, right-click and select Register Web Service.
4. In the WSDL registration wizard, paste the URL in the WSDL URL field.
5. Click Next and complete the wizard to register the WSDL. 6. Click the Mark this item as complete icon in the Upgrade Log Analysis window.
Old repository format
Problem: The WSDL file for the web service uses an old web service repository format (versions earlier than API Gateway 7.3.0).
Solution: You must re-register the WDSL in the web service repository. Perform the following steps:
Axway API Gateway 7.5.2
Policy Developer Guide 206
5 General configuration
1. Click the Old repository format hyperlink to locate the web service to be re-registered.
2. Right-click the web service, select Resynchronize Web Service, and select Yes.
3. Copy the original WSDL URL to the clipboard, and select Cancel from the wizard.
4. Right-click the web service node, select Delete, and select Yes.
5. On that web service group, right-click, and select Register Web Service.
6. In the WSDL registration wizard, paste the URL in the WSDL URL field.
7. Click Next and complete the wizard to register the WSDL. 8. Click the Mark this item as complete icon in the Upgrade Log Analysis window.
Web Service error: Failed to find binding for operation
Problem: The WSDL file the web service has no binding for a particular operation.
Solution: You must re-register the WDSL in the web service repository. Perform the steps listed in Old repository format on page 206.
OAuth Client Application Registry
Problem: A new mechanism for authenticating OAuth client application users in the REST servlet was introduced in API Gateway version 7.4.0. This issue only occurs if you are upgrading from versions earlier than API Gateway 7.4.0.
Solution: You must configure OAuth authentication settings in Policy Studio. Click Server
Settings in the Policy Studio tree and select Security > Client Application Registry. In the Circuit for Authentication field, select a policy for authenticating users. This policy must authenticate the user against a user store of your choice and set the message attributes authentication.subject.role and user.email.The message attribute authentication.subject.role must be set to either admin or resourceowner. For more information on the Client Application Registry settings, see the API Gateway OAuth User Guide.
A sample policy for authenticating users is provided in apigateway/samples/oauth/authzserver/sampleUserAuthnPolicy.xml. This sample policy authenticates the user credentials against the local user store and sets the two required attributes on the message whiteboard, which are used to complete authentication and authorization process. If you use the sample policy, you must manually add a role (for example, role=admin) for the regadmin and sampleuser users. To add the role in Policy Studio, select Environment Configuration > Users and Groups > Users and add the role on the Attributes tab for each user. For more information on adding users, see the API Gateway Administrator Guide.
Migrated resolver for web service
Problem: In API Gateway 7.5.2, WebService resolvers are migrated to path resolvers during upgrade, because the WebService resolver had issues if the web service was renamed.
Solution: The migration to the path resolver removes this issue. The upgrade log contains the following minor warning if this migration affects a web service:
Axway API Gateway 7.5.2
Policy Developer Guide 207
5 General configuration
StockQuoteService Migrated resolver on path '/svcpath'. Confirm path is correct.
In some cases, the migration of the WebService resolver results in a conflict with another path resolver. In this case, the path resolver is renamed to avoid conflict. You are alerted to this with the following critical warning:
StockQuoteService Migrated resolver on path '/svcpath' was renamed to '/*** Path
Conflict ‘/svcpath’' to avoid conflict. Please update appropriately.
You must enter a new unique path.
Discarded Contivo filter
Problem: The Contivo filter is not supported in API Gateway 7.5.1.
Solution: We recommend that you replace this filter with the Execute Data Map filter.
Example warnings and recommended solutions
This section describes some warnings displayed by Policy Studio and provides recommended solutions.
Fastest scripting language not used
Problem: A warning appears if you are using a Scripting Language filter in your old installation with the Language field set to JavaScript (Rhino engine JRE7 and earlier).
Solution: Change the Language of the filter to JavaScript and ensure that the JavaScript syntax in the script conforms with Nashorn engine syntax. Alternatively, you can ignore the warning, meaning that the script continues to work but not with the optimal performance.
Cassandra connection details
Problem: A warning about the Cassandra connection details appears when you are upgrading from API Gateway versions earlier than 7.5.1 to 7.5.2. If you upgrade your entity store configuration using sysupgrade, you can set the Cassandra connection details for the 7.5.2 installation using the upgrade command options --cass_
host, --cass_port, --cass_username and --cass_password. If you have done this correctly, you can ignore the warning.
If you upgrade your entity store configuration in Policy Studio, the Cassandra settings are set to the default settings (for example, localhost).
Solution: After the upgrade, ensure that the Cassandra connection details are correct. Axway API Gateway 7.5.2
Policy Developer Guide 208
5 General configuration
ActiveMQ path update
Problem: A warning appears if ActiveMQ is enabled in your old installation, reminding you to update the Shared Directory field if necessary. Upgrading your entity store in Policy Studio does not automatically update the Shared Directory field or backup the data. This warning indicates you might need to take some actions.
If you upgrade your entity store configuration using sysupgrade, and the Shared Directory field is an absolute path under the old installation directory (for example, /opt/Axway/7.3.1/apigateway/activemq), sysupgrade automatically updates the directory to be the equivalent directory under the new installation directory (for example, /opt/Axway/7.5.2/apigateway/activemq), and copies the data over to the new installation.
If you upgrade your entity store configuration using sysupgrade, and the Shared Directory field is an absolute path that is unrelated to the installation directory (for example, /mynetworkdrive/activemq), sysupgrade backs up the data, but does not update the Shared Directory field. Solution: After the upgrade, ensure that the path defined in the Shared Directory field for ActiveMQ is not an absolute path that can be accessed by both the old and new installations of API Gateway. You can ignore the warning if the field points to a directory that is not shared between the old and new installations, for example, any non-absolute path.
Default SSL ciphers/options not used
Problem: If an API Gateway group or Node Manager configuration contains an SSL interface that has old SSL settings (default ciphers and SSLv2/v3 allowed), a warning appears suggesting that you reconfigure the SSL settings. Similar warnings are generated for system ports and custom ports. Solution: Reconfigure the affected HTTPS listeners to use the recommended ciphers and protocol settings. Alternatively, you can ignore these warnings.
Amazon Web Services filters
Problem: A warning appears if an Amazon Web Services filter without a setting for either AWS
Credential or Client settings is found.
Solution: During the upgrade, dummy settings are added to affected AWS filters. A warning message indicates the affected filters. Replace the dummy settings with valid values, so the filters work correctly.
API Gateway KPS collection
Problem: A warning appears when configuration from an old installation does not contain the KPS schema required by the OAuth Client Application Registry. This warning is only relevant if the configuration is imported directly through Policy Studio and has not been upgraded using the sysupgrade command.
Axway API Gateway 7.5.2
Policy Developer Guide 209
5 General configuration
Solution: You can import the required schema from the configuration fragment in samples/oauth/authzserver/APIServerKPSDefinition.xml.
KPS table PortalExternalClientStore missing
Problem: A warning appears when configuration from an old installation does not contain the KPS table PortalExternalClientStore. This table is required by API Manager. This warning is only relevant if the configuration is imported directly through Policy Studio and has not been upgraded using the sysupgrade command.
Solution: You can import the required schema from the configuration fragment in samples/oauth/authzserver/APIServerKPSDefinition.xml.
OAuth resource owner login
Problem: This warning appears if an old installation is configured to use the same cookie name for both OAuth client and OAuth server configurations. It is a minor issue that only affects test environments where client and server share the same host name (for example, localhost).
Solution: Change the cookie name for OAuth logins on either the client or the server.
OAuth services interface
Problem: This warning appears when multiple listeners implementing OAuth services are found in the old configuration. Upgrade can only successfully upgrade canonical listeners that follow the naming construct of OAuth 2.0 Services.
Solution: Ensure that the Servlet and Path definitions of additional OAuth listeners match those of the default listener OAuth 2.0 Services. If the standard listener definition is not in the configuration, it can be imported from samples/oauth/authzserver/config.xml.
OAuth KPS definitions missing
Problem: A warning appears when configuration from an old installation does not contain the KPS schema required for OAuth token storage. This warning is only relevant if the configuration is imported directly through Policy Studio and has not been upgraded using the sysupgrade command.
Solution: You can import the required schema from the configuration fragment in samples/oauth/authzserver/OAuthTokenKPSDefinition.xml.
OAuth authorizations table missing
Problem: A warning appears when configuration from an old installation does not contain the KPS schema required for OAuth authorization storage.This warning is only relevant if the configuration is imported directly through Policy Studio and has not been upgraded using the sysupgrade command.
Axway API Gateway 7.5.2
Policy Developer Guide 210
5 General configuration
Solution: You can import the required schema from the configuration fragment in samples/oauth/authzserver/OAuthTokenKPSDefinition.xml.
Oracle Security Service Module settings (10g)
Overview
An Oracle Security Service Module (SSM) integrates a secured application (in this case, the API Gateway) with an Oracle Entitlements Server (OES) 10g so that security administration (for example, roles, resources, and policies) is delegated to the Oracle Entitlements Server 10g. An SSM must be installed on the machine hosting the application to be secured by the Oracle Entitlements Server 10g. The SSM runs in-process with the secured application, which improves performance and onthe-wire security.
In Policy Studio, select the Environment Configuration > Server Settings node in the tree, and select Security> Security Service Module in the right pane. The Security Service
Module settings enable you to configure the API Gateway to act as a Java SSM. For more details on Oracle Entitlements Server 10g and SSMs, see the Oracle Entitlements Server website.
Note
Oracle SSM is required only for integration with Oracle OES 10g. Oracle SSM is not required for integration with Oracle OES 11g. OES 10g was previously known as BEA AquaLogic Enterprise Security (ALES). Some items, such as schema objects, paths, and so on, may still use the ALES name. Prerequisites
Before configuring the settings on the Security Service Module tab, you must perform the following prerequisite tasks.
Test the SSM installation
Because the API Gateway is running a Java SSM internally, it is recommended that the example Java SSM client that ships with the OES installation is set up and configured. This example can be found in the following directory:
/ales32-ssm/java-ssm/examples/JavaAPIExample
Follow the instructions in the README file in this directory to test the installation. When the testing of the JavaAPIExample is complete, all the configuration files for an SSM instance are located in the /ales32-ssm/java-ssm/SSM-Name directory, where SSM-Name is the name of the SSM setup when testing the example.
Axway API Gateway 7.5.2
Policy Developer Guide 211
5 General configuration
Configure the API Gateway classpath
The API Gateway classpath must be updated to include the JARs and configuration files for the SSM instance. The jvm.xml file must be updated so that various environment variables and the SSMName are updated to reflect the installation of the Java SSM. At minimum, the following must be updated in jvm.xml:
<Environment name="BEA_HOME" value="/opt/apps/bea" >
<Environment name="INSTANCE_NAME" value="SSM-Name" >
For example, to modify the classpath, place the following jvm.xml in the conf directory of the API Gateway installation:
<!--Additional JVM settings to run with Oracle Entitlements Server BEA_HOME must be
set to the location
where the SSM is installed -->
<ConfigurationFragment>
<!-- Environment variables -->
<!-- change these to match location where SSM has been installed and configured ->
<Environment name="BEA_HOME" value="/opt/apps/bea" />
<Environment name="ALES_SHARED_HOME" value="$BEA_HOME/ales32-shared" />
<!-- Name of the SSM running in the API Gateway, replace the "SSM-Name" with the
name of the SSM for
the API Gateway -->
<Environment name="INSTANCE_NAME" value="SSM-Name" />
<Environment name="INSTANCE_HOME" value="$BEA_HOME/ales32-ssm/java-ssm/instance/
$INSTANCE_NAME" />
<Environment name="PDP_PROXY" value="$INSTANCE_HOME/pdpproxy" />
<!-- Location of the Java SSM libraries -->
<!-- <ClassDir name="$BEA_HOME" /> -->
<ClassDir name="$BEA_HOME/ales32-ssm/java-ssm/lib" />
<ClassDir name="$BEA_HOME/ales32-ssm/java-ssm/lib/providers/ales" />
<!-- Add location of the SSM configuration to classpath -->
<ClassPath name="$INSTANCE_HOME/config/" />
<!-- Additional JVM parameters based on the %JAVA-OPTIONS% of set-env script in
SSM instance running
in API Gateway $BEA_HOME/ales32-ssm/java-ssm/instance/ssm-name/config -->
<VMArg name="-Dwles.scm.port=7005" />
<VMArg name="-Dwles.arme.port=8000" />
<VMArg name="-Dwles.config.signer=Oracle Entitlements Serverdemo.oracle.com" />
<VMArg name="-Dlog4j.configuration=file:$INSTANCE_HOME/config/log4j.properties" />
<VMArg name="-Dlog4j.ignoreTCL=true" />
<VMArg name="-Dwles.ssl.passwordFile=$ALES_SHARED_HOME/keys/password.xml" />
<VMArg name="-Dwles.ssl.passwordKeyFile=$ALES_SHARED_HOME/keys/password.key" />
<VMArg name="-Dwles.ssl.identityKeyStore=$ALES_SHARED_HOME/keys/identity.jceks" />
<VMArg name="-Dwles.ssl.identityKeyAlias=wles-ssm" />
<VMArg name="-Dwles.ssl.identityKeyPasswordAlias=wles-ssm" />
Axway API Gateway 7.5.2
Policy Developer Guide 212
5 General configuration
<VMArg name="-Dwles.ssl.trustedCAKeyStore=$ALES_SHARED_HOME/keys/trust.jks" />
<VMArg name="-Dwles.ssl.trustedPeerKeyStore=$ALES_SHARED_HOME/keys/peer.jks" />
<VMArg name="-Djava.io.tmpdir=$INSTANCE_HOME/work/jar_temp" />
<VMArg name="-Darme.configuration=$INSTANCE_HOME/config/WLESarme.properties" />
<VMArg name="-Dales.blm.home=$INSTANCE_HOME" />
<VMArg name="-Dkodo.Log=log4j" />
<VMArg name="-Dwles.scm.useSSL=true" />
<VMArg name="-Dwles.providers.dir=$BEA_HOME/ales32-ssm/java-ssm/lib/providers" />
<VMArg name="-Dpdp.configuration.properties.location=$PDP_PROXY/
PDPProxyConfiguration.properties" />
</ConfigurationFragment>
Centralize all trace output
Oracle’s Java SSM uses log4j to output any diagnostics. You can also add these messages to the API Gateway trace output by adding the log4j that ships with the API Gateway to the following file:
/ales32-ssm/java-ssm/SSM-NAME/conf/log4j.properties
Then the log4j.rootCategory=WARN, A1, ASIlogFile line includes a new appender called VordelTrace as follows:
log4j.rootCategory=WARN, A1, ASIlogFile, VordelTrace
Add the configuration for this new appender by adding the following line to the file:
log4j.appender.VordelTrace=com.vordel.trace.VordelTraceAppender
You can now start the API Gateway so that it runs with the Java SSM classpath and the centralized trace output.
Further information
For more details on configuring and testing SSMs, see the Oracle SSM Installation and Configuration Guide.
Settings
On the Security Service Module settings window, configure the following fields on the Settings
tab:
Enable Oracle Security Service Module:
Select whether to enable the API Gateway instance to act as an SSM. This setting is disabled by default.
Axway API Gateway 7.5.2
Policy Developer Guide 213
5 General configuration
Application Configuration Name:
Enter the Application Configuration name for the SSM instance. This is the name of your runtime application used by OES (for example, for monitoring purposes).
Configuration Name:
Enter the OES Configuration name for the SSM instance to be stored in the OES Configuration Repository. Configuration names share the same name as their Policy Domain names.
Application Configuration Properties:
Click Add to specify optional configuration properties as name-value pairs. Enter a Name and Value in the Properties dialog. Repeat to specify multiple properties.
Policy Domain Name:
Enter the OES Policy Domain name for the SSM instance. Policy Domains contain policy definitions (target resource, permission set, and policy). Policy Domain names share the same name as their Configuration names. Name authority definition settings
Configure the following field on the Name Authority Definition tab:
Name Authority Definition File:
Click the Browse button at the bottom right to configure the Name Authority Definition file for the SSM. This is an XML file that specifies the naming authority definition required for the API Gateway. For example, a specified XML file named apigatewayNameAuthorityDefinition.xml file should contain the following settings:
<AuthorityConfig>
<AuthorityDefinition name="apigatewayResource" delimiters="/\">
<Attribute name="protocol" type="MULTI_TOKEN" authority="URLBASE" />
</AuthorityDefinition>
<AuthorityDefinition name="apigatewayAction" delimiters="/">
<Attribute name="action" type="SINGLE_VALUE_TERMINAL" />
</AuthorityDefinition>
</AuthorityConfig>
Kerberos configuration
The Kerberos Configuration under Server settings > Security > Kerberos in the node tree enables you to configure instance-wide Kerberos settings on API Gateway and to upload a Kerberos configuration file to API Gateway. This configuration file contains information on the location of the Kerberos Key Distribution Center (KDC), as well as which encryption algorithms, encryption keys, and domain realms to use. You can also configure trace options for the various APIs used by the Kerberos system, such as the Generic Security Services (GSS) and Simple and Protected GSS-API Negotiation (SPNEGO) APIs. Axway API Gateway 7.5.2
Policy Developer Guide 214
5 General configuration
UNIX/Linux platforms ship with a native implementation of the GSS library, which API Gateway can leverage. You can specify the location of the GSS library in this configuration window.
For more details on different Kerberos setups with API Gateway, see API Gateway Kerberos Integration Guide.
Kerberos configuration file — krb5.conf
The Kerberos configuration file ( krb5.conf) d efines the location of the Kerberos KDC, supported encryption algorithms, and default realms in the Kerberos system. Both Kerberos clients and Kerberos services that are configured for API Gateway use this file. Kerberos clients need to know the location of the KDC so that they can obtain a Ticket Granting Ticket (TGT). They also need to know what encryption algorithms to use and what realm they belong to. Kerberos services d o not need to call the KDC to request a TGT, but they still require the information on supported encryption algorithms and default realms contained in the krb5.conf file. A Kerberos client or service identifies the realm it belongs to because the realm is appended to its Kerberos principal name after the @ symbol. Alternatively, if the realm is not specified in the principal name, the Kerberos client or service assumes the realm to be the default_realm specified in the krb5.conf file. The file specifies only one default_realm, but you can specify a number of additional named realms. The default_realm setting is in the [libdefaults] section of the krb5.conf file. It points to a realm in the [realms] section. This setting is not required. The text input field in the Kerberos configuration window displays a default configuration for krb5.conf. You can type and modify the configuration as needed, and then click OK to upload it to your API Gateway configuration. Alternatively, if you have an existing krb5.conf file that you want to use, select Load File and open to the configuration file. The contents of the file are displayed in the text area, and you can edit and upload it to API Gateway. Note
Refer to your Kerberos documentation for more information on the settings that can be configured in the krb5.conf file.
Advanced settings
You can configure various tracing options for the underlying Kerberos API using the check boxes on the Advanced settings tab. Trace output is always written to the /trace directory of your API Gateway installation.
l Kerberos Debug Trace– Enables extra tracing from the Kerberos API layer.
l SPNEGO Debug Trace – Switches on extra tracing from the SPNEGO API layer.
l Extra Debug at Login– Provides extra tracing information during login to the Kerberos KDC. Axway API Gateway 7.5.2
Policy Developer Guide 215
5 General configuration
Native GSS library
The Generic Security Services API (GSS-API) is an API for accessing security services, including Kerberos. Implementations of the GSS-API ship with the UNIX/Linux platforms and can be leveraged by API Gateway when it is installed on these platforms. The fields on this tab allow you to configure various aspects of the GSS-API implementation for your target platform. Use Native GSS Library:
Select this to use the operating system's native GSS implementation. This option only applies to API Gateway installations on the UNIX/Linux platforms.
Note
These are instance-wide settings. If you select Use Native GSS Library, it is used for all Kerberos operations, and all Kerberos clients and services must be configured to load their credentials natively.
If the native library is used, the following features are not supported:
l The SPNEGO mechanism
l The WS-Trust for SPNEGO standard (requires the SPNEGO mechanism)
l The SPNEGO over HTTP standard (requires the SPNEGO mechanism)
l Signing and encrypting using the Kerberos session keys
It is possible to use the KERBEROS mechanism with the SPNEGO over HTTP standard, but this would be non-standard. Native GSS Library Location:
If you have opted to use the native GSS library, enter the location of the GSS library in the field provided, for example, /usr/lib/libgssapi.so. On Linux, the library is called libgssapi.so. .
Note
This setting is only required when this library is in a non-default location.
Native GSS Trace:
Use this option to enable debug tracing for the native GSS library.
Axway API Gateway 7.5.2
Policy Developer Guide 216
Manage deployments
6
This section describes how to manage API Gateway deployments.
Manage API Gateway deployments
217
Deploy API Gateway configuration
219
Compare and merge API Gateway configurations
223
Manage admin users
226
Manage API Gateway deployments
Overview
You can use Policy Studio to deploy configuration to API Gateway instances running in groups in an API Gateway domain. P olicy Studio enables you to edit API Gateway configuration and then deploy it to the server instance, where it can be reloaded later. You can deploy modified configuration to multiple API Gateway instances in a group managed by an Admin Node Manager. The API Gateway Manager web console also enables you to deploy configuration packages to API Gateway instances running in groups in a domain, to create groups and API Gateway instances, and to manage administrator users. In this way, Policy Studio and the API Gateway Manager enable policy developers and administrators to centrally manage the policies that are enforced at all nodes throughout the network. In addition, Policy Studio enables you to compare and merge differences between versions of the same policy. Policies can be merged, and deployed to any running instance that is managed by Policy Studio. One of the most powerful uses of this centralized management capability is in transitioning from a staging environment to a production environment. For example, policies can be developed and tested on the staging environment, and when ready, they can be deployed to all instances deployed in the production environment. Create a project in Policy Studio
Note
Before starting Policy Studio, you should first ensure that the Admin Node Manager and the server instance that you wish to deploy to have been started.
To create a new Policy Studio project, select File > New Project, and follow the steps in the wizard. For more details, see Create a Policy Studio project on page 48.
Axway API Gateway 7.5.2
Policy Developer Guide 217
6 Manage deployments
Alternatively, if a project has already been created, select File > Open Project in the main menu, or click Open Project on the landing page. For more details, see Manage API Gateway connections on page 182.
Edit a project configuration in Policy Studio
When you create or open a Policy Studio project and make a server connection, this loads the project configuration and displays it in the following format:
ProjectName [ServerInstanceType]
For example: MyDevProject [API Gateway]
When a project configuration is loaded, its services are displayed in the Policy Studio tree on the left. Expand one of the top-level nodes in the tree to display additional details (for example, APIs, Policies, Resources, o r Environment Configuration). When editing a project configuration, you can deploy updates using the Deploy button in the toolbar (alternatively, press F6). For more details, see Deploy API Gateway configuration on page 219.
Deploy to a server in Policy Studio
To deploy to a running API Gateway instance in a group, click Deploy in the toolbar, and follow the steps in the wizard. For more details, see Deploy API Gateway configuration on page 219.
Tip
You must connect to the Admin Node Manager server to deploy API Gateway configuration or manage multiple API Gateway instances in your network. Manage deployments in API Gateway Manager
In the web-based API Gateway Manager tool, the TOPOLOGY section on the Dashboard tab enables you to create API Gateway groups and instances, and to deploy configuration packages to running servers in API Gateway groups.
For details on how to access the API Gateway Manager, see Start the API Gateway tools on page 47.
Compare and merge configurations in Policy
Studio
You can compare and merge differences between the currently loaded API Gateway configuration with a configuration stored in a deployment package (.fed file). Click the Compare button on the Policy Studio toolbar to select a .fed file to compare the current configuration against. The results are displayed in the Compare/Merge tab.
Axway API Gateway 7.5.2
Policy Developer Guide 218
6 Manage deployments
For example, you can view the differences made to particular fields in an Authentication filter that occurs in both configurations. When a difference is located, you can merge the differences, and thereby update the fields in the Authentication filter in the current configuration with the field values for the same Authentication filter in the deployment package.
For more details, see Compare and merge API Gateway configurations on page 223.
Manage administrator users in API Gateway
Manager
You can add new administrator users to enable role-based access to the API Gateway configuration managed by Policy Studio and API Gateway Manager. The default administrator user has access to all API Gateway features in Policy Studio and API Gateway Manager, and can view and modify all API Gateway configurations.
To add or remove administrator users, click the Settings > Admin Users tab in the API Gateway Manager. For more details, see Manage admin users on page 226. For more details on role-based access, see the API Gateway Administrator Guide.
Configure policies in Policy Studio
You can use Policy Studio to manage the configuration of your policies, which can then be deployed to running instances of Axway API Gateways. For details on configuring the full range of message filters (for example, for Authentication, Authorization, or Content Filtering), see the other sections in this guide.
Deploy API Gateway configuration
Overview
You can edit API Gateway configuration in a Policy Studio project, and d eploy to specified API Gateway instances running in an API Gateway group. You can deploy projects based on existing configuration, configuration packages, factory configuration, or a running API Gateway instance.
Policy Studio also enables you to create configuration packages ( .fed, .pol, or .env files), and to deploy projects based on configuration packages to API Gateway instances.
You can also deploy API Gateway configuration packages in the API Gateway Manager web console. Alternatively, you can use the managedomain script to create and deploy deployment packages ( .fed files) on the command line.
Axway API Gateway 7.5.2
Policy Developer Guide 219
6 Manage deployments
Deploy configuration in Policy Studio
You can deploy updates to a currently loaded configuration when editing the configuration in Policy Studio. To deploy a currently loaded configuration, perform the following steps:
1. Click the Deploy button on the right in the toolbar.
2. In the Open Connection dialog, in the Saved Sessions section, select the server session to use from the list. You can edit a session name by entering a new name and clicking Save. You can also click the appropriate button to Add, Clone, or Remove saved sessions.
3. In the Connection Details section, configure the following:
l Host:
Enter the server host to connect to. The default is localhost.
l Port:
Enter the port to connect on. The default Admin Node Manager port is 8090.
l User name:
The deployment service is protected by HTTP basic authentication. Enter the administrator user name to use to authenticate to the server. For more details, see Manage admin users on page 226.
l Password:
Enter the password for the administrator user.
4. Click Advanced to enter the URL of the deployment service exposed by the server. This setting is optional. The default Admin Node Manager URL is https://localhost:8090/api.
5. Click Next to configure deployment options.
If an advisory warning has been configured, you must click Next again. For more details, see the API Gateway Administrator Guide.
6. In the Select the servers(s) you wish to deploy to section, select an API Gateway group from the Group list, and select the server instance(s) in the box below.
If the server uses a different API Gateway encryption passphrase for its environment, click Advanced, select The target server uses a different passphrase, and enter the Passphrase used by the target server.
7. Click Next, and wait for the deployment to complete.
8. Click Finish.
Note
You must connect to the Admin Node Manager server to deploy API Gateway configuration or manage multiple API Gateway instances in your network. View deployment results in Policy Studio
When you click Deploy, the Deployment Results screen is displayed, and deployment to each server occurs sequentially. Feedback is provided using icons in the Task column, and text in the Status column. When the configuration has deployed, click Finish.
Axway API Gateway 7.5.2
Policy Developer Guide 220
6 Manage deployments
Cancel deployments
You can cancel deployments by clicking the Cancel button. Feedback is provided in the Status column. You cannot cancel a deployment when it has started. The wizard performs the cancellation at the end of the current deployment, with all remaining deployments being canceled. Deployment errors
Client-side and server-side errors can occur. Client-side errors are displayed in the System Trace in the Console view. If any server-side deployment errors occur during the deployment process, you can review these in the Deployment Error Log view. This is displayed at the bottom of the screen when you click Finish, and lists any errors that occur for each instance. The corresponding Console Deployment Log is also available in the Console view.
Redeploy
When you have deployed a configuration to one or more instances, you can click back through the wizard to change your selections and redeploy, without needing to exit and relaunch the wizard.
API Gateway configuration packages
You can deploy c onfiguration based on API Gateway configuration packages in Policy Studio and in the API Gateway Manager web console. API Gateway includes the following types of configuration package:
l A deployment package is a .fed file that contains all API Gateway configuration. This includes policies, listeners, external connections, users, certificates, and environment settings. l A policy package is a .pol file that contains policies, listeners, external connections, and environment settings. l An environment package is an .env file that contains users, certificates, and environment settings. The content of the .fed file is equivalent to the combined contents of the .pol and
.env files.
l A package property is a name-value pair that applies to a specific configuration package ( .fed ,
.pol , or .env). Specifying a property associates metadata with the configuration in that package. For example, the Name property with a value of Default Factory
Configuration is associated with a default installation. For more details on configuration packages and properties, see the API Gateway DevOps Deployment Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 221
6 Manage deployments
Create a configuration package in Policy Studio
You can create an API Gateway configuration package for a currently loaded project configuration. To create a package ( .fed, .pol, or .env), perform the following steps:
1. In the main menu, select File > Save Package followed by the appropriate option:
l Deployment Package ( .fed)
l Policy Package ( .pol)
l Environment Package ( .env)
2. Enter a file name, and click Save.
Configure package properties in Policy Studio
You can view or modify API Gateway configuration package properties for a currently loaded project configuration. To view and modify configuration properties, perform the following steps:
1. In the Policy Studio tree, and select Environment Configuration > Package Properties > Policy or Environment.
2. If you wish to create any additional properties (for example, Department), click the green (+) button on the right, and enter a property value (for example, Engineering).
3. If you wish to remove a property, click the red (x) button on the right of the property.
4. Click Save at the top right of the screen.
Deploy packages in Policy Studio
You can use the Policy Studio to create projects based on configuration packages. For more details, see Create a Policy Studio project on page 48.
You can deploy the configuration as normal using the Deploy button in the toolbar. For more details, see Deploy configuration in Policy Studio on page 220.
Deploy packages in API Gateway Manager
You can also use the API Gateway Manager web console to deploy configuration packages to a group of API Gateway instances. This functionality is available on the default Dashboard tab. For more details, see the API Gateway Administrator Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 222
6 Manage deployments
Deploy packages on the command line
You can create and deploy a deployment package ( .fed ) using the managedomain --menu command in the following directory:
Windows
INSTALL_DIR\Win32\bin
UNIX/Linux
INSTALL_DIR/posix/bin
The deployment options for the managedomain --menu command are as follows:
18)
19)
20)
21)
22)
Deploy to a group
List deployment information
Create deployment archive
Download deployment archive
Update deployment archive properties
For more details, see the API Gateway Administrator Guide.
Compare and merge API Gateway
configurations
Overview
In the Policy Studio, you can compare the currently loaded API Gateway configuration with a configuration stored in a deployment package ( .fed file). You can also merge any differences between the configurations.
Differences between configurations are identified as additions, deletions, or conflicts. When merging configurations, you can choose which differences to merge.
Note
The currently loaded configuration can only be compared with a configuration stored in a deployment package ( .fed) or in a server configuration file ( .xml). You cannot compare against a policy package ( .pol) or environment package ( .env). For more information on configuration packages, see Deploy API Gateway configuration on page 219.
Compare and merge configurations
To compare the currently loaded configuration against the configuration in a .fed file, follow these steps:
Axway API Gateway 7.5.2
Policy Developer Guide 223
6 Manage deployments
1. Click the Compare button on the Policy Studio toolbar.
2. In the Comparing target with field, click the Browse button to choose a .fed file to compare the configuration with.
3. Enter the passphrase for the configuration, if one has been set, and click OK .The configurations are compared and the results are displayed in a tree view. Only entities with differences are shown.
4. To see detailed differences, click a configuration entity in the tree. The differences for that entity are displayed in the Difference Details pane.
5. To merge differences into the currently loaded configuration, select the check box next to each difference to be merged, and click the Merge button at the top right of the window.
Note
If you modify the currently loaded configuration after the Compare and Merge tab is opened, click the Refresh button to refresh the comparison and show any new differences.
Comparison results
The following figure shows the result of a comparison:
Axway API Gateway 7.5.2
Policy Developer Guide 224
6 Manage deployments
The Difference Counts pane shows the number of differences in total, the number of additions, the number of deletions, and the number of conflicts.
The Differences tree view shows all of the differences in the configuration entities:
l Entities with green plus icon are additions. These entities exist in the .fed file but not in the currently loaded configuration.
l Entities with a red minus icon are deletions. These entities exist in the currently loaded configuration but not in the .fed file.
l Entities with a yellow warning icon are conflicts. These entities exist in both configurations but are not the same.
The Difference Details pane shows the values of the fields in each configuration when you click on an entity in the tree view. The second column shows the values of the fields in the .fed file, and the third column shows the values of the fields in the currently loaded configuration. The fields that are different in each configuration are highlighted.
In the preceding figure:
l The cron expression Run at 2am every day in Jan is a deletion.
l The cron expression Run at 2:10pm and at 2:44pm every Wednesday in the
month of March is an addition.
l The user sampleuser is a conflict, because the password field has a different value in each configuration.
Some configuration entities contain references to other entities. In this case, an icon is displayed for the field in the Difference Details pane. Double-click a row with an icon to view the differences for those entities. Filter differences
To filter nodes from the Differences tree view based on their type, click View Nodes, and select from the following options:
l Additions
l Deletions
l Conflicts
All differences are shown by default.
Select differences for merging
To select nodes for merging from the Differences tree view based on their type, click View
Nodes, and select from the following options: l Additions
l Deletions
Axway API Gateway 7.5.2
Policy Developer Guide 225
6 Manage deployments
l Conflicts
Additions are selected by default.
Manage admin users
Overview
When logging into the Policy Studio or API Gateway Manager, you must enter the user credentials stored in the local admin user store to connect to the API Gateway server instance. Admin users are responsible for managing API Gateway instances using the API Gateway management APIs. To manage admin users, click the Settings > Admin Users tab in the API Gateway Manager.
Note
Admin users provide access to the API Gateway configuration management features available in the Policy Studio and API Gateway Manager. However, API Gateway users provide access to the messages and services protected by the API Gateway. For more details, see Manage API Gateway users on page 243. Admin user privileges
After installation, a single admin user is defined in the API Gateway Manager with a user name of admin. Admin user rights in the system include the following:
l Add another admin user
l Delete another admin user
l Update an admin user
l Reset admin user passwords
Note
An admin user cannot delete itself.
Remove the default admin user
If you need to remove the default admin user, perform the following steps:
1. Add another admin user.
2. Log in as the new admin user.
3. Delete the default admin user.
The Admin Users tab displays all existing admin users. You can use this tab to add, update, and delete admin users. These tasks are explained in the sections that follow.
Axway API Gateway 7.5.2
Policy Developer Guide 226
6 Manage deployments
Admin user roles
The API Gateway uses Role-Based Access Control (RBAC) to restrict access to authorized users based on their assigned roles in a domain. Using this model, permissions to perform specific system operations are assigned to specific roles only. This simplifies system administration because users do not need to be assigned permissions directly, but instead acquire them through their assigned roles. For example, the default admin user ( admin) has the following user roles:
l Policy Developer
l API Server Administrator
l KPS Administrator
API Gateway user roles and privileges
User roles have specific tools and privileges assigned to them. These define who can use which tools to perform what tasks. The user roles provided with the API Gateway assign the following privileges to admin users with these roles:
Role
Tool
Privileges
API Server
API Gateway Read/write access to API Gateway Manager. Administrator
Manager
API Gateway Manager
Read-only access to API Gateway Manager. Deployer
Deployment scripts
Deploy a new configuration.
KPS
API Gateway Manager
Perform create, read, update, delete (CRUD) operations on data in a Key Property Store (KPS). Policy Studio
Download, edit, deploy, version, and tag a configuration.
API Server
Operator
Administrator
Policy
Developer
Note
A single admin user typically has multiple roles. For example, in a development environment, a policy developer admin user would typically have the following roles:
l Policy Developer
l API Server Administrator
Axway API Gateway 7.5.2
Policy Developer Guide 227
6 Manage deployments
Add a new admin user
Complete the following steps to add a new admin user to the system:
1. Click the Settings > Admin Users tab in API Gateway Manager.
2. Click the Create button.
3. In the Create New Admin User dialog, enter a name for the user in the Username field.
4. Enter a user password in the Password field. 5. Re-enter the user password in the Confirm Password field. 6. Select roles for the user from the list of available roles (for example, Policy Developer and API Server Administrator).
7. Click Create.
Remove an admin user
To remove an admin user, select it in the Username list, and click Delete. The admin user is removed from the list and from the local admin user store.
Reset an admin user password
You can reset an admin user password as follows:
1. Select the admin user in the Username list.
2. Click the Edit button.
3. Enter and confirm the new password in the Password and Confirm Password fields. 4. Click OK.
Manage admin user roles
You can manage the roles that are assigned to specific admin users as follows:
1. Select the admin user in the Username list.
2. Click the Edit button.
3. Select the user roles to enable for this admin user in the dialog (for example, Policy
Developer and/or API Server Administrator). 4. Click OK.
Axway API Gateway 7.5.2
Policy Developer Guide 228
6 Manage deployments
Edit API Gateway user roles
To add or delete specific API Gateway roles, you must edit the available roles in the adminUsers.json and acl.json files in the conf directory of your API Gateway installation.
For more details on role-based access, see the API Gateway Administrator Guide.
Configure a password policy for admin users
To configure the password policy that applies to admin user passwords, perform the following steps:
1. Click the Settings > Admin Users tab in API Gateway Manager.
2. Select Password Policy enabled to enable the password policy rules on this page. This is not selected by default.
3. Configure the following in PASSWORD RULES:
l Password must not be equal to the account name: The password cannot be identical to the admin user name. This is selected by default.
l Password must not be the reverse of the account name: The password cannot be the reverse of the admin user name. This is selected by default.
l Password must not contain the account name: The password cannot contain the admin user name. This is selected by default.
l Minimum password length: The password must be the specified minimum length. Defaults to 4 characters. If no value is specified, this rule is ignored. l Password history length: Enter the number of previous passwords to be compared. This is not specified by default, and this rule is ignored.
l Minimum character differences from last password: Enter the minimum number of different characters from the last password. This is not specified by default, and this rule is ignored.
l Password lifetime (days): Enter how long the password is valid for in days. This is not specified by default, and this rule is ignored.
4. Configure the following in PASSWORD COMPOSITION RULES:
l Minimum uppercase characters: Defaults to 1 uppercase alphabetic character.
l Minimum lowercase characters: Defaults to 1 lowercase alphabetic character.
l Minimum numeric characters: Defaults to 1 numeric character.
l Minimum special characters: Defaults to 1 special character ( [email protected]#$%^&*()-_
=+\[{}];:"",< >/?).
If no value is specified, the rule are ignored.
5. Click Apply when finished.
Axway API Gateway 7.5.2
Policy Developer Guide 229
Environment configuration
7
This section describes how to configure your API Gateway environment. For example, this includes X.509 certificates and keys, users, caches, system alerts, and so on. For details on API Gateway listeners, see Configure API Gateway instances on page 279. See also External connections on page 371.
Manage X.509 certificates and keys
230
Manage API Gateway users
243
Configure system alerts
245
Policy execution scheduling
256
Global caches
259
Cross-Origin Resource Sharing
268
Key Property Store
273
Manage X.509 certificates and keys
Overview
For API Gateway to trust X.509 certificates issued by a specific Certificate Authority (CA), you must import that CA's certificate into the API Gateway's trusted certificate store. For example, if API Gateway is to trust secure communications (SSL connections or XML Signature) from an external SAML Policy Decision Point (PDP), you must import the PDP certificate, or the issuing CA certificate into the API Gateway certificate store. In addition to importing CA certificates, you can import and create server certificates and private keys in the certificate store. These can be stored locally or on an external Hardware Security Module (HSM). You can also import and create public-private key pairs. For example, these can be used with the Secure Shell (SSH) File Transfer Protocol (SFTP) or with Pretty Good Privacy (PGP).
View certificates and keys
To view the certificates and keys stored in the certificate store, select Environment Configuration > Certificates and Keys > Certificates in the tree. Certificates and keys are listed on the following tabs in the Certificates window:
l Certificates with Keys: Server certificates with associated private keys
l Certificates: Server certificates without any associated private keys
l CA: Certificate Authority certificates with associated public keys
Axway API Gateway 7.5.2
Policy Developer Guide 230
7 Environment configuration
You can search for a specific certificate or key by entering a search string in the text box at the top of each tab, which automatically filters the tree. Certificate management options
The following options are available at the bottom right of the window:
l Create/Import: Click to create or import a new certificate and private key. For details, see Configure an X.509 certificate on page 231.
l Edit: Select a certificate, and click to edit its existing settings.
l View: Select a certificate, and click to view more detailed information.
l Remove: Select a certificate, and click to remove the certificate from the certificate store.
l Keystore: Click this to export or import certificates to or from a Java keystore. For details, see Manage certificates in Java keystores on page 242.
Configure an X.509 certificate
To create a certificate and private key, click Create/Import. The Configure Certificate and
Private Key dialog is displayed. This section explains how to use the X.509 Certificate tab on this dialog.
Axway API Gateway 7.5.2
Policy Developer Guide 231
7 Environment configuration
Create a certificate
Configure the following settings to create a certificate:
l Subject:
Click Edit to configure the Distinguished Name (DName) of the subject.
l Alias Name:
This mandatory field enables you to specify a friendly name (or alias) for the certificate. Alternatively, you can click Use Subject to add the DName of the certificate in the text box instead of a certificate alias. l Public Key: Click Import to import the subject's public key (usually from a PEM or DER-encoded file).
l Version:
This read-only field displays the X.509 version of the certificate.
l Issuer:
This read-only field displays the distinguished name of the CA that issued the certificate.
l Choose Issuer Certificate:
Select to explicitly specify an issuer certificate for this certificate (for example, to avoid a potential clash or expiry issue with another certificate using the same intermediary certificate). You can then click the browse button on the right to select an issuer certificate. This setting is not selected by default.
l Not valid before:
Select a date to define the start of the validity period of the certificate.
l Not valid after:
Select a date to define the end of the validity period of the certificate.
Axway API Gateway 7.5.2
Policy Developer Guide 232
7 Environment configuration
l Sign Certificate:
You must click this button to sign the certificate. The certificate can be self-signed, or signed by the private key belonging to a trusted CA whose key pair is stored in the certificate store.
Import certificates
You can use the following buttons to import or export certificates into the certificate store:
l Import Certificate:
Click to import a certificate (for example, from a .pem or .der file). l Export Certificate:
Click to export the certificate (for example, to a .pem or .der file).
Configure a private key
Use the Private Key tab to configure details of the private key. By default, private keys are stored locally (for example, in the API Gateway certificate store). They can also be provided by an OpenSSL engine, or stored on a Hardware Security Module (HSM) if required. API Gateway supports PKCS#11-compatible HSM devices. For example, this includes Thales nShield Solo (provided locally with the API Gateway API Gateway Appliance), SafeNet Luna SA, and so on.
Axway API Gateway 7.5.2
Policy Developer Guide 233
7 Environment configuration
Private key stored locally
If the private key is stored in the API Gateway certificate store, or on the Thales nShield Solo HSM provided locally with the appliance, select Private key stored locally. The following options are available for keys stored locally:
l Private key stored locally:
This read-only field displays details of the private key.
l Import Private Key:
Click to import the subject's private key (usually from a PEM or DER-encoded file).
l Export Private Key:
Click to export the subject's private key to a PEM or DER-encoded file.
Note
When using the Thales nShield Solo HSM provided locally with the API Gateway API Gateway Appliance, select Private key stored locally. For more details, see the API Gateway Appliance Installation and Administration Guide.
Private key provided by OpenSSL engine
If the private key that corresponds to the public key in the certificate is provided by an OpenSSL engine, select Private key provided by OpenSSL Engine. Configure the following fields to associate a key provided by the OpenSSL engine with the current certificate:
l Engine name:
Enter the name of the OpenSSL engine to use to interface to an HSM. All vendor implementations of the OpenSSL Engine API are identified by a unique name. See your vendor's OpenSSL engine implementation or HSM documentation to find out the name of the engine. l Key Id:
Enter the key ID used to uniquely identify a specific private key from all others stored on an HSM. When you complete this dialog, the private key is associated with the certificate that you are currently editing. Private keys are identified by their key ID by default.
Private key stored on external HSM
If the private key that corresponds to the public key stored in the certificate resides on an external HSM, select Private key stored on Hardware Security Module (HSM) , and enter the name of the Certificate Realm.
Note
To use the API Gateway's PKCS#11 engine to access objects in an external HSM, the corresponding HSM provider and certificate realms must also be configured. For more details, see Configure HSMs and certificate realms on page 235. Axway API Gateway 7.5.2
Policy Developer Guide 234
7 Environment configuration
Configure HSMs and certificate realms
Certificate realms are abstractions of private keys and public key certificates, which mean that policy developers do not need to enter HSM-specific configuration such as slots and key labels. Instead, if a private key exists on an HSM, the developer can configure the certificate to show that its private key uses a specific certificate realm, which is simply an alias for a private key (for example, JMS
Keys ).
For example, on the host machine, an administrator could configure the JMS Keys certificate realm, and create a keystore for the realm, which requires specific knowledge about the HSM (for example, PIN, slot, and private key label). The certificate realm is the alias name, while the keystore is the actual private keystore for the realm.
Note
This section does not apply when using the Thales nShield Solo HSM provided locally with the API Gateway Appliance. Instead select Private key stored locally, and see the API Gateway Appliance Installation and Administration Guide.
Manage HSMs with keystoreadmin
The keystoreadmin script enables you to perform the following tasks:
l Register an HSM provider
l List registered HSM providers
l Create a certificate realm
l List certificate realms
For example, if a policy developer is using JMS, and wants to indicate that private keys exist on an HSM, they could indicate that the certificate is using the JMS Keys certificate realm. On each instance using the configuration, it is the responsibility of the administrator to create the JMS
Keys certificate realm.
For more details, enter keystoreadmin in the following directory, and perform the instructions at the command prompt:
Windows
INSTALL_DIR\apigateway\Win32\bin
UNIX/Linux
INSTALL_DIR/apigateway/posix/bin
Use keystoreadmin in interactive mode
When you enter keystoreadmin without arguments, this displays an interactive menu with the following options:
Axway API Gateway 7.5.2
Policy Developer Guide 235
7 Environment configuration
Option
Description
When to use
1
Change
When registering HSMs or configuring certificate realms, you must choose the local group and instance to configure.
group or
instance
2
List
Display the HSMs that are currently registered.
registered
HSM
providers
3
provider
Before creating certificate realms, you must first register the HSM. This option guides you through the steps. The HSM must be installed, configured, and active, and you must know the full path to the HSM device driver (PKCS#11). You give the HSM an alias (for example, LunaSA), which you use later when registering certificate realms.
List
List configured certificate realms and associated keystores.
Register an
HSM
4
Certificate
Realms
5
Create a
Create a keystore and assign it to a certificate realm.
Certificate
Realm
Step 1—Register an HSM provider
You must first register an HSM provider as follows:
1. Open a command prompt in the API Gateway bin directory (for example, apigateway\Win32\bin).
2. Enter the keystoreadmin command.
3. Select option 3) Register an HSM provider.
4. If prompted, select the appropriate API Gateway group or instance.
5. You are prompted for a provider alias name. The alias is local only. For example, if registering a LunaSA HSM, you might enter the LunaSA alias.
6. For convenience, keystoreadmin searches for supported HSM drivers. If found, it shows the list of supported drivers. If none are found, this does not mean the driver does not exist. Axway API Gateway 7.5.2
Policy Developer Guide 236
7 Environment configuration
You must see your HSM documentation for the location of the drivers. For example:
Choose from one of the following:1) C:\LunaSA\cryptoki.dllo) Otherq)
Quit
7. If successful, keystoreadmin loads the driver and displays its details. For example:
Registering HSM provider...
Initializing HSM...
Crypto Version:2.20
Manufacter Id:SafeNet, Inc.
Library Description:Chrystoki
Library Version:5.1Device registered.
Step 2—Create a certificate realm and associated
keystore
To create a certificate realm and associated keystore, perform the following steps:
1. Open a command prompt in the API Gateway bin directory (for example, apigateway\Win32\bin).
2. Enter the keystoreadmin command.
3. Select option 5) Create a Certificate Realm.
4. You are prompted to enter a certificate realm name. This certificate realm name is used in when configuring the private key of the corresponding X.509 certificate. The realm name is case sensitive (for example, JMS Keys).
5. The registered HSMs are listed. For example, select option 1) HSM. 6. The command connects to the selected HSM, and a list of available slots is displayed. Select the slot containing the private key to use for the certificate realm (for example, select slot 1).
7. You are prompted to input the PIN passphrase for the slot. The passphrase will not echo any output. 8. When you enter the correct PIN passphrase for the slot, this displays a list of private keys. Choose the key to use for the certificate realm. For example:
Choose from one of the following:
1) server1_priv
2) jms_priv
q) Quit
Select option:2
Axway API Gateway 7.5.2
Policy Developer Guide 237
7 Environment configuration
9. You are prompted for a file name for the keystore. For example:
Certificate realm filename [jms keys.ks]:Successfully created the certificate
realm:JMS KeysPress any key to continue...
10. The keystore is output to the API Gateway instance directory. For example:
apigateway/groups/group-2/instance-1/conf/certrealms/jms keys.ks
Note
Each API Gateway instance must have its certificate realm configured. When finished creating certificate realms, you must restart the API Gateway instance for the changes to take effect.
Step 3—Start the API Gateway when using an HSM
When the API Gateway is configured to use certificate realms, these realms are initialized on startup, and a connection to the corresponding HSM is established. This requires the PIN passphrase for the specific HSM slots. At startup, you can manually enter the required HSM slot PIN passphrase, or you can automate this instead.
Start API Gateway with manually entered PIN passphrase
When the API Gateway is configured to use an HSM, the API Gateway stops all processing, prompts for the HSM slot PIN passphrase, and waits indefinitely for input. For example:
INFO
07/Jan/2015:16:31:54 Initializing certificate realm 'JMS Keys'...
Enter passphrase for Certificate Realm, "JMS Keys":
The API Gateway does not reprompt if the PIN passphrase is incorrect. It logs the error and continues, while any services that use the certificate realm cannot use the HSM.
Start API Gateway with automatic PIN passphrase
You can configure the API Gateway to start and initialize the HSM by invoking a command script on the operating system to obtain the HSM slot PIN passphrase. This enables the API Gateway for automatic startup without manually entering the PIN passphrase. To configure an automatic PIN passphrase, perform the following steps:
1. Edit the API Gateway instance’s vpkcs11.xml configuration file. For example:
apigateway/groups/group-2/instance-1/conf/vpkcs11.xml
Axway API Gateway 7.5.2
Policy Developer Guide 238
7 Environment configuration
2. Add a PASSPHRASE_EXEC command that contains the full path to the script that executes and obtains the passphrase. The script should write the passphrase to stdout, and should have the necessary operating system file and execute protection settings to prevent unauthorized access to the PIN passphrase. The following example shows a vpkcs11.xml file that invokes the hsmpin.sh to echo the passphrase:
<?xml version="1.0" encoding="utf-8"?>
<ConfigurationFragment provider="cryptov">
<Engine name="vpkcs11" defaultFor="">
<EngineCommand when="preInit" name="REALMS_DIR"
value="$VINSTDIR/conf/certrealms" />
<EngineCommand when="preInit" name="PASSPHRASE_EXEC"
value=""$VDISTDIR/hsmpin.sh"" />
</Engine>
</ConfigurationFragment>
3. The API Gateway provides the certificate realm as an argument to the script, so you can use the same script to initialize multiple realms. The following examples show scripts that write a PIN of 1234 to stdout when initializing the JMS Keys certificate realm:
Example hsmpin.bat file on Windows
@echo off
IF [%1]==[] GOTO _END
::Strip out the double quotes around arg
SET REALM=%1
SET REALM=%REALM:"=%
IF "%REALM%"=="JMS Keys" ECHO 1234
Example hsmpin.sh file on Linux/UNIX
#!/bin/shcase $1 in"JMS Keys")echo 1234;;esac
Configure SSH key pairs
To configure public-private key pairs in the certificate store, select Environment Configuration > Certificates and Keys >Key Pairs . The Key Pairs window enables you to add, edit, or delete OpenSSH public-private key pairs, which are required for the Secure Shell (SSH) File Transfer Protocol (SFTP). Add a key pair
To add a public-private key pair, click Add on the right, and configure the following settings in the dialog:
Axway API Gateway 7.5.2
Policy Developer Guide 239
7 Environment configuration
l Alias:
Enter a unique name for the key pair.
l Algorithm:
Enter the algorithm used to generate the key pair. Defaults to RSA .
l Load:
Click to select the public key or private key files to use. The Fingerprint field is auto-populated when you load a public key. Note
The keys must be OpenSSH keys. RSA keys are supported, but DSA keys are not supported. The keys must not be passphrase protected.
Edit a key pair
To edit a public-private key pair, select a key pair alias in the table, and click Edit on the right. For example, you can load a different public key and private key. Alternatively, double-click a key pair alias in the table to edit it. You can delete a selected key pair from the certificate store by clicking Remove on the right. Alternatively, click Remove All.
Manage OpenSSH keys
You can use the ssh-keygen command provided on UNIX to manage OpenSSH keys. For example:
l The following command creates an OpenSSH key:
ssh-keygen -t rsa
l The following command converts an ssh.com key to an OpenSSH key:
ssh-keygen -i -f ssh.com.key > open.ssh.key
l The following command removes a passphrase (enter the old passphrase, and enter nothing for the new passphrase):
ssh-keygen -p
l The following command outputs the key fingerprint:
ssh-keygen -lf ssh_host_rsa_key.pub
Axway API Gateway 7.5.2
Policy Developer Guide 240
7 Environment configuration
Configure PGP key pairs
To configure Pretty Good Privacy (PGP) key pairs in the certificate store, select Environment
Configuration > Certificates and Keys > PGP Key Pairs. The PGP Key Pairs window enables you to add, edit, or delete PGP public-private key pairs. Add a PGP key pair
To add a PGP public-private key pair, click the Add on the right, and configure the following settings in the dialog:
l Alias:
Enter a unique name for the PGP key pair.
l Load:
Click Load to select the public key and private key files to use.
Note
The PGP keys added must not be passphrase protected.
Edit a PGP key pair
To edit a PGP key pair, select a key pair alias in the table, and click Edit on the right. For example, you can load a different public key and private key. Alternatively, double-click a key pair alias in the table to edit it. You can delete a selected PGP key pair from the certificate store by clicking Remove on the right. Alternatively, click Remove All.
Manage PGP keys
You can use the freely available GNU Privacy Guard (GnuPG) tool to manage PGP key files (available from http://www.gnupg.org/). For example:
l The following command creates a PGP key:
gpg --gen-key
For more details, see http://www.seas.upenn.edu/cets/answers/pgp_keys.html
l The following command enables you to view the PGP key:
gpg -a --export
l The following command exports a public key to a file:
Axway API Gateway 7.5.2
Policy Developer Guide 241
7 Environment configuration
gpg --export -u 'UserName ' -a -o public.key
l The following command exports a private key to a file:
gpg --export-secret-keys -u 'UserName ' -a -o private.key
l The following command lists the private keys:
gpg --list-secret-keys
Global import and export options
This section describes global import and export options available when managing certificates and keys.
Import and export certificates and keys
The following global configuration options apply to both the X.509 Certificate and Private Key tabs:
l Import Certificate + Key:
Use this option to import a certificate and a key (for example, from a .p12 file).
l Export Certificate + Key:
Use this option to export a certificate and a key (for example, to a .p12 file).
Click OK when you have finished configuring the certificate and private key.
Manage certificates in Java keystores
You can also export a certificate to a Java keystore. You can do this by clicking Keystore on the main Certificates window. Click the browse button at beside the Keystore field at the top right to open an existing keystore, or click New Keystore to create a new keystore. Choose the name and location of the keystore file, and enter a passphrase for this keystore when prompted. Click Export
to Keystore , and select a certificate to export.
Similarly, you can import certificates and keys from a Java keystore into the certificate store. To do this, click Keystore on the main Certificates window. On the Keystore window, browse to the location of the keystore by clicking the browse button beside the Keystore field. The certificates/keys in the keystore are listed in the table. To import any of these keys to the certificate store, select the box next to the certificate or key to import, and click Import to Trusted certificate store. If the key is protected by a password, you are prompted for this password.
Axway API Gateway 7.5.2
Policy Developer Guide 242
7 Environment configuration
You can also use the Keystore window to view and remove existing entries in the keystore. You can also add keys to the keystore and to create a new keystore. Use the appropriate button to perform any of these tasks.
Further information
For more details on supported security features, see the API Gateway Security Guide. Manage API Gateway users
Overview
By default, the API Gateway user store contains the configuration data for managing API Gateway user information. The API Gateway user store is typically used in a development environment, and is useful for demonstration purposes. In a production environment, user information may be stored in existing user Identity Management repositories such as Microsoft Active Directory, Oracle Access Manager, CA SiteMinder, and so on. For more details, see the relevant API Gateway Integration Guide.
Note
API Gateway users provide access to the messages and services protected by API Gateway. However, admin users provide access to the API Gateway configuration management features available in Policy Studio, Configuration Studio, and API Gateway Manager. API Gateway users
API Gateway users specify the user identity in the API Gateway user store. This includes details such as the user name, password, and X.509 certificate. API Gateway users must be a member of at least one user group. In addition, users can specify optional attributes, and inherit attributes at the group level. To view all existing users, select the Environment Configuration > Users and Groups > Users node in the tree. The users are listed in the table on the main panel. You can find a specific user by entering a search string in the Filter field.
Add API Gateway users
You can create API Gateway users on the Users page. Click the Add button on the right. To specify the new user details, complete the following fields on the General tab:
l User Name:
Enter a name for the new user.
Axway API Gateway 7.5.2
Policy Developer Guide 243
7 Environment configuration
l Password:
Enter a password for the new user.
l Confirm Password:
Re-enter the user's password to confirm.
l Signing Key:
Click to load the user certificate from the Certificate Store. For details on how to create and import certificates, see Manage X.509 certificates and keys on page 230.
You can also specify optional user attributes on the Attributes tab, which is explained in the next section. API Gateway user attributes
You can specify attributes at the user level and at the group level on the Attributes tab. Attributes specify user configuration data (for example, attributes used to generate SAML attribute assertions).
The Attributes tab enables you to configure user attributes as simple name-value pairs. The following are examples of user attributes:
l role=admin
l [email protected]
l dept=eng
l company=axway
You can add user attributes by clicking the Add button. Enter the attribute name, type, and value in the fields provided. The Encrypted type refers to a string value that is encrypted using a wellknown encryption algorithm or cipher.
API Gateway user groups
API Gateway user groups are containers that encapsulate one or more users. You can specify attributes at the group level, which are inherited by all group members. If a user is a member of more than one group, that user inherits attributes from all groups (the superset of attributes across the groups of which the user is a member).
To view all existing groups, select the Environment Configuration > Users and Groups > Groups node in the tree. The user groups are listed in the table on the main panel. You can find a specific group by entering a search string the Filter field.
Add API Gateway user groups
You can create user groups on the Groups page. Click the Add button on the right to view the Add
Group dialog. To specify the new group details, complete the following fields on the General tab:
Axway API Gateway 7.5.2
Policy Developer Guide 244
7 Environment configuration
l Group Name:
Enter a name for the new group.
l Members:
Click the Add button to display the Add Group Member dialog, and select the members to add to the group. You can also specify optional attributes at the group level on the Attributes tab. For more details, see API Gateway user attributes on page 244. Update API Gateway users or groups
To edit details for a specific user or group, select it in the list, and click the Edit button on the right. Enter the updated details in the Edit User or Edit Group dialog.
To delete a specific user or group, select it in the list, and click the Remove button on the right. Alternatively, to delete all users or Groups, click the Remove All button. You are prompted to confirm all deletions.
Configure system alerts
Overview
This topic shows the API Gateway system alert capabilities. System alerts and events are usually sent when a filter fails, but they can also be used for notification purposes. API Gateway can send system alerts to several alert destinations, including a Windows Event Log, UNIX/Linux syslog, SNMP Network Management System, Check Point Firewall-1, email recipient, Amazon Simple Notification Service (SNS), or Twitter.
There main steps when configuring API Gateway to send system alerts are:
1. Configure an alert destination
2. Configure an alert filter
Configure an alert destination
The first step in configuring API Gateway to send alerts is to configure an alert destination. This section describes the destinations to which the API Gateway can send alerts to. You can configure these alert destinations under the Environment Configuration > Libraries > Alerts node in the Policy Studio tree.
Axway API Gateway 7.5.2
Policy Developer Guide 245
7 Environment configuration
Syslog (local or remote)
Many types of UNIX and Linux provide a general purpose logging utility called syslog. Both local and remote processes can send logging messages to a centralized system logging daemon, known as syslog, which in turn writes the messages to the appropriate log files. You can configure the level of detail at which syslog logs information. This enables administrators to centrally manage how log files are handled, rather than separately configuring logging for each process. Each type of process logs to a different syslog facility . There are facilities for the kernel, user processes, authorization processes, daemons, and a number of place-holders used by site-specific processes. For example, API Gateway enables you to log to facilities such as auth, daemon, ftp, local0-7, and syslog itself.
Remote syslog
To configure a remote syslog alert destination, perform the following steps:
1. Click the Environment Configuration > Libraries > Alerts node, and then Add > Syslog
Remote at the bottom on the right.
2. The Syslog Server dialog enables you to specify details about the machine on which the syslog daemon is running. API Gateway connects to this daemon and logs to the specified facility when the alert event is triggered. Complete the following fields on the Syslog Server dialog:
l Name: Enter a name for this alert destination.
l Host: Enter the host name or IP address of the machine where the syslog daemon is running.
l Facility: Select the facility that API Gateway sends alerts to.
3. Click OK.
Local syslog (UNIX only)
To configure a local syslog alert destination, perform the following steps:
1. Click the Environment Configuration > Libraries > Alerts node, and then click Add > Syslog Local (UNIX only) at the bottom of the window on the right.
2. The Syslog Server dialog enables you to specify where the alert is sent when the alert event is triggered. Complete the following fields on the Syslog Server dialog:
l Name: Enter a name for this alert destination.
l Facility: Select the facility that API Gateway sends alerts to.
3. Click OK.
Axway API Gateway 7.5.2
Policy Developer Guide 246
7 Environment configuration
Windows Event Log
This alert destination enables alert messages to be written to the local or a remote Windows Event Log. To add a Windows Event Log alert destination, perform the following steps:
1. Click the Environment Configuration > Libraries > Alerts node in the Policy Studio tree, and then click Add > Windows Event Log at the bottom of the window on the right.
2. The Windows Event Log Alerting dialog enables you to specify the machine of the event log API Gateway sends alerts to. Complete the following fields on this dialog:
l Name: Enter a name for the alert destination.
l UNC Server name: Enter the UNC (Universal Naming Code) of the machine where the event log resides. For example, to send alerts to the event log running on a machine called \\NT_SERVER, enter \\NT_SERVER as the UNC name for this host.
3. Click OK.
Check Point FireWall-1 (OPSEC)
API Gateway complies with Open Platform for Security (OPSEC). OPSEC compliance is awarded by Check Point Software Technologies to products that have been successfully integrated with at least one of their products. In this case, API Gateway has been integrated with the Check Point FireWall-1 product.
FireWall-1 is the industry leading firewall that provides network security based on a security policy created by an administrator. Although OPSEC is not an open standard, the platform is recognized worldwide as the standard for interoperability of network security, and the alliance contains over 300 different companies. OPSEC integration is achieved through a number of published APIs, which enable third-party vendors to interoperate with Check Point products. To configure a FireWall-1 alert destination, perform the following steps:
1. Click the Environment Configuration > Libraries > Alerts node in the Policy Studio tree, and click Add > OPSEC at the bottom of the window on the right.
2. The OPSEC Alerting dialog enables you to specify details about the machine on which FireWall-1 is installed, the port it is listening on, and how to authenticate to the firewall. The API Gateway connects to the specified firewall when the alert event is triggered and prevents further requests for the particular client that triggered the alert. The following configuration settings must be set:
l sam_server auth_port: The port number used to establish Secure Internal Communications (SIC) connections with the firewall.
l sam_server auth_type: The authentication method used to connect to the firewall.
Axway API Gateway 7.5.2
Policy Developer Guide 247
7 Environment configuration
l sam_server ip: The host name or IP address of the machine that hosts Check Point Firewall.
l sam_server opsec_entity_sic_name: The firewall's SIC name.
l opsec_sic_name: The OPSEC application SIC Name (application's full DName defined by the VPN-1 SmartCenter Server).
l opsec_sslca_file: The name of the file containing the OPSEC application's digital certificate.
3. Click OK.
You can store configuration information in a file, and load it by clicking Browse. Alternatively, use Template to load the required settings into the text area, and add the configuration values manually.
For API Gateway to establish the SSL connection to the firewall, the opsec_sslca_file specified must be uploaded to the API Gateway machine. To do this, click Add at the bottom of the window.
For more information on OPSEC settings, see the documentation for your OPSEC application.
SNMP Network Management System
This alert destination enables API Gateway to send Simple Network Management Protocol (SNMP) traps to a Network Management System (NMS).To configure an SNMP alert destination, perform the following steps:
1. Click the Environment Configuration > Libraries > Alerts node in the Policy Studio tree, and then click Add > SNMP at the bottom of the window on the right.
2. The SNMP Alerting dialog enables you to specify details about the NMS that API Gateway sends alerts to. Complete the following fields:
l Host: The host name or IP address of the machine on which the NMS resides.
l Port: The port on which the NMS is listening. l Timeout: The timeout in seconds for connections from API Gateway to the NMS.
l Retries: The number of retries that should be attempted whenever a connection failure occurs.
l SNMP Version: Select the version of SNMP to use for this alert.
3. Click OK.
Axway API Gateway 7.5.2
Policy Developer Guide 248
7 Environment configuration
Email recipient
This alert destination enables alert messages to be sent by email. To add an email alert destination, perform the following steps:
1. Click the Environment Configuration > Libraries > Alerts node in the Policy Studio tree, and click Add > Email at the bottom on the right.
2. The Email Alerting dialog enables you to configure how the email alert is sent. Complete the following:
l Name: Enter a name for this alert destination.
l Email Recipient (To): Enter the recipient of the alert mail in this field. Use a semicolon-separated list of email addresses to send alerts to multiple recipients.
l Email Sender (From): Email alerts appear from the sender email address specified here. Note
Some mail servers do not allow relaying mail when the sender in the From field is not recognized by the server.
l Email Subject: Email alerts use the subject specified in this field.
3. In the SMTP Server Settings, specify the following fields:
l Outgoing Mail Server (SMTP): Specify the SMTP server that API Gateway uses to relay the alert email.
l Port: Specify the SMTP server port to connect to. Defaults to port 25.
l Connection Security: Select the connection security used to send the alert email ( SSL, TLS, or NONE). Defaults to NONE.
4. If you are required to authenticate to the SMTP server, specify the following fields in Log on
Using:
l User Name: Enter the user name for authentication.
l Password: Enter the password for the user name specified.
5. Finally, you can select the Email Debugging setting to find out more information about errors encountered by API Gateway when attempting to send email alerts. All trace files are written to the /trace directory of your API Gateway installation. This setting is not selected by default.
6. Click OK.
Axway API Gateway 7.5.2
Policy Developer Guide 249
7 Environment configuration
Amazon SNS
This alert destination enables alert messages to be sent to the Amazon Simple Notification Service (SNS). Amazon SNS is a managed push messaging service that can be used to push to mobile devices and Internet connected smart devices, as well as to other distributed services. For more information on Amazon SNS, go to http://aws.amazon.com/sns/. To add an Amazon SNS alert destination, perform the following steps:
1. Click the Environment Configuration > Libraries > Alerts node in the Policy Studio tree.
2. Click Add > Amazon SNS at the bottom of the window on the right.
3. Complete the following fields on the AWS SNS Alert dialog:
l Name: Enter a name for this alert destination.
l AWS Credential: Click the browse button to select your AWS security credentials (API key and secret) to be used by API Gateway when connecting to Amazon SNS.
l Region: Select the region appropriate for your deployment. You can choose from the following options:
o US East (Northern Virginia)
o US West (Oregon)
o US West (Northern California)
o EU (Ireland)
o Asia Pacific (Singapore)
o Asia Pacific (Tokyo)
o Asia Pacific (Sydney)
o South America (Sao Paulo)
o US GovCloud
l Client settings: Click the browse button to select the AWS client configuration to be used by API Gateway when connecting to Amazon SNS. For more details, see Configure Amazon SQS queue listener on page 363.
l Topic ARN: Enter the topic Amazon Resource Name (ARN) to send alerts to. When you create a topic, Amazon SNS assigns a unique ARN to the topic, which includes the service name (for example, SNS), the region, the AWS ID of the user, and the topic name. Whenever a publisher or subscriber needs to perform any action on the topic, they should reference the unique topic ARN. The ARN is returned as part of the API call to create the topic. For example, arn:aws:sns:us-east-
Axway API Gateway 7.5.2
Policy Developer Guide 250
7 Environment configuration
1:1234567890123456:mytopic is the ARN for a topic named mytopic created by a user with the AWS account ID 123456789012 and hosted in the US East region. l Subject: Enter the subject of the alert to be sent to Amazon SNS.
4. Click OK.
Twitter
This alert destination enables API Gateway to send tweet alerts to Twitter. Twitter uses the OAuth open authentication standard. To enable API Gateway to send tweet alerts using the Twitter API, you first need to do the following:
l Create a Twitter account to represent you as the user
l Register a custom application for your API Gateway instance, which posts alerts on the user's behalf
Twitter requires that API calls are made for both the user and the application. The Twitter API requires the following credentials:
l Consumer key of registered applications
l Consumer secret key of registered application
l Access token allowing application to post on behalf of a user
l Access token secret to verify the access token
Twitter uses this information to determine which application is calling the API, and verifies that the Twitter user you are attempting to make API requests on behalf of has authorized access to their account using the specified application. Twitter identifies and authenticates all requests as coming from both the user performing the request and the registered API Gateway application working on the user's behalf. Register a client application
To use the Twitter API, you must create a Twitter account, and register a client application for API Gateway. If you have not already created a Twitter account, register a new account using the instructions on http://www.twitter.com. When you have created an account, register a client application for API Gateway:
1. Go to http://dev.twitter.com.
2. On the Twitter toolbar, select Your apps.
3. Click Register a new app.
4. Enter the details for your custom application. Some details are arbitrary, but you must specify the following values:
l Application Type: Select Client.
l Default Access Type: Select Read & Write.
Axway API Gateway 7.5.2
Policy Developer Guide 251
7 Environment configuration
Note
The Application Name might already be registered to another user, so you may need to specify a different unique name.
5. Click Register Application. Each client application you register is provisioned a consumer key and consumer secret. These are used, in conjunction with the OAuth library, to sign every request you make to the API. Using this signing process, Twitter trusts that the traffic identifying itself as you is indeed you.
6. Select your registered application, and select My Access Token. This provides you with an access token and an access token secret. You must store these safely.
Configure a Twitter alert destination
To configure a Twitter alert destination, perform the following steps:
1. Click the Environment Configuration > Libraries > Alerts node in the Policy Studio tree.
2. Click Add > Twitter at the bottom of the window on the right.
3. The Twitter Alerting dialog enables you to specify credentials for the Twitter user that API Gateway sends an alert to:
l Consumer Key: The consumer key of your registered application.
l Consumer Secret: The consumer secret of your registered application.
l Access Token: The access token that represents you.
l Access Token Secret: The access token secret that represents you.
Configure an alert filter
Typically, an Alert filter is placed on the failure path of another filter in the policy. For example, to configure an alert if a schema validation fails 10 times within a 5000 millisecond period for a specified web service. In this case, you would place the Alert filter on the failure path from the Schema Validation filter, as shown in the following policy example.
When editing policies, you can drag and drop the Alert filter from the Monitoring filter group.
Axway API Gateway 7.5.2
Policy Developer Guide 252
7 Environment configuration
General settings
Configure the following settings on the Alert filter window:
Name:
Enter a descriptive name for the filter to display in a policy.
Alert Type:
Select the severity level of the alert (Error, Warn, or Info). This option is only relevant for alert destinations that support severity levels, such as the Windows Event Log.
Notifications settings
The Notifications tab enables you to configure the alert destinations. Any alert destinations that are already configured are shown under the respective alert destination type on the left of the window. You can also create new alert destinations, and edit or delete existing alert destinations directly from this window. Select an existing alert destination
To select an existing alert destination, follow these steps:
1. Click the check box next to the alert destination on the left of the window. Alternatively, click the check box next to the alert destination type to select all alert destinations of that type (for example, all Email destinations).
2. Choose the message to use for the alert destination on the right side of the window.
l To set the message for an email destination, select Use the Default Message to use the message from the Default Message tab, select Use the following message to enter a custom message, or select Load from file to load a message from a file.
You can select the Content type of a custom message or a message loaded from a file (for example, as text/html). You can also register new MIME content types by clicking the Registered Types button.
l To set the message for all other destinations, select Use the Default Message to use the message from the Default Message tab, or select Use the following message to enter a custom message.
The following figure shows an example of an email alert destination with a text/html custom message.
Axway API Gateway 7.5.2
Policy Developer Guide 253
7 Environment configuration
The following figure shows an example of an SNMP alert destination that uses the default message.
Create a new alert destination
To create a new alert destination, click Add at the top left and choose from the following options: For more details, see Configure an alert destination on page 245.
l Email
l OPSEC
l Syslog Local (UNIX only)
l SNMP
l Windows Event Log
l Syslog Remote
l Twitter
Axway API Gateway 7.5.2
Policy Developer Guide 254
7 Environment configuration
Edit or delete an existing alert destination:
To edit or delete an existing alert destination, select the destination on the left and click Edit or Delete.
Call this policy when alert is triggered:
Click the browse button to select a policy to be used by API Gateway when an alert is triggered. Tracking settings
The Tracking tab enables you to configure how often alerts are sent. Configure the following settings:
Accumulated number of messages:
Enter the number of times this filter can be invoked before the alert is sent. The default value is 1.
In time period (secs):
Enter the time period in which the accumulated number of messages can occur before an alert is triggered. The default is 60 seconds.
Track per client:
Select this option to record the accumulated number of messages in the specified time period for each client. This option is selected by default.
Default message settings
The Default Message tab enables you to configure a default message for alerts. Enter the message text to appear in the alert in the Message to send field. You can enter message attributes using selectors, which API Gateway looks up and expands at runtime. For example, instead of sending a generic alert stating Authentication Failed, you can use a message attribute to include the ID of the user whose authentication failed. The following examples show how to use message attributes in alert messages.
Authentication failure for user:${authentication.subject.id}.
${alert.number.failures} authentication failures have occurred in
${alert.time.period} seconds.
${alert.number.failures} exceptions have occurred in policy ${circuit.name}.
The last exception was ${circuit.exception} with path ${circuit.path}.
For more information on selectors, see Select configuration values at runtime on page 854.
Note
An alert message is not required for alerts sent to an OPSEC firewall.
Axway API Gateway 7.5.2
Policy Developer Guide 255
7 Environment configuration
Policy execution scheduling
Overview
You can configure a policy execution scheduler at the level of the API Gateway instance. This enables you to schedule the execution of any policy on a specified date and time in a recurring manner. The API Gateway provides a pre-configured library of schedules to select from when creating a policy execution scheduler. You can also add your own schedules to the globally available library in the Policy Studio. You can use policy execution scheduling in any policy (for example, to perform a message health check). This feature is also useful when polling a service to enforce a Service Level Agreement (for example, to ensure the response time is less than 1000 ms, and if not, to send an alert). Cron expressions
In the Policy Studio, policy execution schedules are based on cron expressions. A cron expression is a string that specifies a time schedule for triggering an event (for example, executing a policy). It consists of six required fields and one optional field, each separated by a space, which together specify when to trigger the event. For example, the following expression specifies to run at 10:15 am every Monday, Tuesday, Wednesday, Thursday, and Friday in 2011:
0 15 10 ? * MON-FRI 2011
Syntax
The following table shows the syntax used for each field:
Field
Values
Special characters
Seconds
0-59
, - * /
Minutes
0-59
, - * /
Hours
0-23
, - * /
Day of Month
1-31
, - * ? / L W
Month
1-12 or JAN-DEC
, - * /
Day of Week
1-7 or SUN-SAT
, - * ? / L #
Axway API Gateway 7.5.2
Policy Developer Guide 256
7 Environment configuration
Field
Values
Special characters
Year (optional) empty or 1970-2199
, - * /
Special characters
The special characters are explained as follows:
Special
character
Description
,
Separates values in a list (for example, MON,WED,SAT means Mondays, Wednesdays, and Saturdays only).
-
Specifies a range of values (for example, 2011-2015 means every year between 2011 and 2015 inclusive).
*
Specifies all values of the field (for example, every minute).
?
Specifies no value in the Day of Month and Day of Week fields. This enables you to specify a value in one field, but not in the other.
/
Specifies time increments (for example, in the Minutes field, 0/15 means minutes 0, 15, 30, and 45, while 5/15 means minutes 5, 20, 35, and 50). Specifying * before the / is the same as specifying 0 as the start value. The / character enables you to turn on every nth value in the set of values for the specified field. For example, 7/6 in the month field only turns on month 7, and does not mean every 6th month.
L
Specifies the last value in the Day of Month and Day of Week fields. In the Day of Month field, this means the last day of the month (for example, January 31, or February 28 in non-leap years). In the Day of Week field, when used alone, this means 7 or SAT. When used after another value, it means the last XXX day of the month (for example, 5L means the last Thursday of the month). When using the L
character, do not specify lists or ranges because this can give confusing results.
W
Specifies the weekday (Monday-Friday) nearest the given day. For example, 15W means the nearest weekday to the 15th of the month. If the 15th is a Saturday, the trigger fires on Friday 14th. If the 15th is a Sunday, it fires on Monday 16th. If the 15th is a Tuesday, it fires on Tuesday 15th. However, if you specify 1W , and the 1st is a Saturday, the trigger fires on Monday 3rd to avoid crossing the month boundary. You can only specify the W character for a single day, and not a range or list of days.
Axway API Gateway 7.5.2
Policy Developer Guide 257
7 Environment configuration
Special
character
Description
#
Specifies the nth XXX weekday of the month in the Day of Week field. For example, a value of FRI#2 means the second Friday of the month. However, if you specify #5, and there are not 5 of the specified Day of the Week in the month, no policy is run that month. When the # character is specified, there can only be one expression in the Day of Week field (for example, 2#1,6#4 is not valid because there are two expressions).
Examples
The following are some of the cron expressions provided in the Schedule Library in the Policy Studio:
Cron expression
Description
0 15 10 ? * *
Run at 10:15am every day.
0 15 10 ? *
6L 2011-2015
Run at 10:15am on every last Friday of every month during the years 2011, 2012, 2013, 2014, and 2015.
0 15 10 ? *
Run at 10:15am on the third Friday of every month.
6#3
0 0 10 1,15 *
Run at 10am on the 1st and 15th days of the month.
?
0 10,44 14 ?
Run at 2:10pm and at 2:44pm every Wednesday in the month of March.
3 WED
0,30 * * ? *
Run every 30 seconds but only on Weekends (Saturday and Sunday).
SAT,SUN
* ?
Run every 5 minutes starting at 2pm and ending at 2:55pm, and every 5 minutes starting at 6pm and ending at 6:55pm, every day.
0 0-5 14 * *
Run every minute starting at 2pm and ending at 2:05pm, every day.
0 0/5 14,18 *
?
Note
Note the following:
l Support for specifying both a Day of Week and a Day of Month value is not complete. You must use the ? or * character in one of these fields.
Axway API Gateway 7.5.2
Policy Developer Guide 258
7 Environment configuration
l Overflowing ranges with a larger number on the left than the right are supported (for example, 21-2 for 9pm until 2am, or OCT-MAR). However, overuse may cause problems with daylight savings (for example, 0 0 14-6 ? * FRI-MON).
Add a schedule
To add a schedule to the globally available library in the Policy Studio, perform the following steps:
1. Select the Environment Configuration > Libraries > Schedules node in the tree.
2. Click the Add button at the bottom of the Schedules window.
3. In the Schedules dialog, enter a Name (for example, Run every 30 seconds).
4. Enter a Cron expression (for example, 0/30 * * * * ?). Alternatively, click the browse button to select an expression in Cron dialog. For more details, see Configure cron expressions on page 868.
5. Click OK.
You can also edit or delete a selected schedule using the appropriate button.
Add a policy execution scheduler
To add a policy execution scheduler in the Policy Studio, perform the following steps:
1. Select the Environment Configuration > Listeners node on the left.
2. Right-click the instance node (for example, API Gateway), and select Add policy execution
scheduler.
3. Click the button next to the Schedule field, select a cron expression in the dialog, and click OK.
4. Click the button next to the Policy field, select a policy in the dialog, and click OK. You can search for a specific policy by entering its name in the text box, and the policy tree is filtered automatically.
5. Click OK.
Global caches
Overview
In cases where a back-end service is serving the same request (and generating the same response) over and over again, it makes sense to use a caching mechanism. When a cache is employed, a unique identifier for the request is cached together with the corresponding response for this request. If an identical request is received, the response can be retrieved from the cache instead of Axway API Gateway 7.5.2
Policy Developer Guide 259
7 Environment configuration
forcing the service to reprocess the identical request and generate the same response. The use of caching in this way helps divert unnecessary traffic from the service and makes it more responsive to new requests.
For example, assume you have deployed a service that returns a list of cities in the USA from an external database, which is then used by a variety of web-based applications. Because the names and quantity of cities in the USA are relatively constant, if the service handles hundreds or thousands of requests every day, this is waste of processing time and effort, especially considering that the database that contains the relatively fixed list of city names is hosted on a separate machine to the service. If you assume that the list of cities in the database does not change very often, it makes sense to use the API Gateway to cache the response from the service that contains the list of cities. Then when a request for this service is identified by the API Gateway, the cached response can be returned to the client. This approach results in the following performance improvements:
l The API Gateway does not have to route the message on to the service, therefore saving the processing effort required, and perhaps more importantly, saving the time it takes for the round trip. l The service does not have to waste processing power on generating the same list over and over again, therefore making it more responsive to requests for other services. l Assuming a naive implementation of database retrieval and caching, the service does not have to query the database (over the network) and collate the results over and over again for every request. The caching mechanism used in the API Gateway offers full control over the size of the cache, the lifetime of objects in the cache, whether objects are cached to disk, and even whether caches can be replicated across multiple API Gateway instances. This topic describes how to configure both local and distributed caches in the API Gateway, and shows examples of how to configure a policy to cache responses.
Local caches
Local caches are used where a single API Gateway instance has been deployed. In such cases, you do not need to replicate caches across multiple running instances of the API Gateway. Add a local cache
In the Policy Studio tree, you can add a local cache by selecting the Environment Configuration > Libraries > Caches node, and clicking the Add button at the bottom right of the window. Select Add Local Cache from the menu. You can configure the following fields on the Configure
Local Cache dialog:
Cache Name:
Enter a name for the cache.
Maximum Elements in Memory:
Enter the maximum number of objects that can be in memory at any one time.
Axway API Gateway 7.5.2
Policy Developer Guide 260
7 Environment configuration
Maximum Elements on Disk:
Sets the maximum number of objects that can be stored in the disk store at any one time. A value of zero indicates an unlimited number of objects.
Eternal:
If this option is selected, objects stored in the caches never expire and timeouts have no effect.
Overflow to Disk:
Select this option if you want the cache to overflow to disk when the number of objects in memory has reached the amount set in the Maximum Elements in Memory field above. Time to Idle:
Determines the maximum amount of time (in seconds) between accesses that an object can remain idle before it expires. A value of zero indicates that objects can idle for infinity, which is the default value. If the Eternal field is selected, this setting is ignored. Time to Live:
Sets the maximum time between when an object is created and when it expires. The default value is zero, which means that the object can live for infinity. If the Eternal field is selected, this setting is ignored.
Persist to Disk:
If selected, the disk store is persisted between JVM restarts. This option is disabled by default.
Disk Expiry Interval:
Configures the number of seconds between runs of the disk expiry thread. The default is 120 seconds.
Disk Spool Buffer Size:
Indicates the size of memory (in MBs) to allocate the disk store for a spool buffer. Writes are made to this memory and then asynchronously written to disk. The default size is 30 MB. If you get OutOfMemory exceptions, you can consider lowering this value. However, if you notice poor performance, you should increase the value.
Eviction Policy:
Select the eviction policy that the cache uses to evict objects from the cache. The default policy is Least Recently Used. However, you can also use First in First Out and Less Frequently
Used. Distributed caches
If you have deployed several API Gateways throughout your network, you need to employ a distributed cache. In this scenario, each API Gateway has its own local copy of the cache but registers a cache event listener that replicates messages to the other caches so that put, remove, expiry, and delete events on a single cache are duplicated across all other caches. Axway API Gateway 7.5.2
Policy Developer Guide 261
7 Environment configuration
Add a distributed cache
You can add a distributed cache by selecting the Environment Configuration > Libraries > Caches tree node, and clicking the Add button at the bottom right of the window. Select Add
Distributed Cache from the menu, and configure the following fields on the Configure
Distributed Cache dialog:
Note
Many of the settings for the distributed cache are identical to those for the local cache. For details on how to configure these fields, see Add a local cache on page 260. The following information refers to fields that are not displayed on both dialogs. Event Listener Class Name:
Enter the name of the listener factory class that enables this cache to register listeners for cache events, such as put, remove, delete, and expire.
Properties Separator:
Specify the character to use to separate the list of properties. Properties:
Specify the properties to pass to the RMICacheReplicatorFactory. The following properties are available:
l replicatePuts=true | false
Determines whether new elements placed in a cache are replicated to other caches. Default is true.
l replicateUpdates=true | false
Determines whether new elements that override (update) existing elements with the same key in a cache are replicated. Default is true.
l replicateRemovals=true
Determines whether element removals are replicated. Default is true.
l replicateAsynchronously=true | false
Determines whether replications are asynchronous (true) or synchronous (false). Default is false.
l replicateUpdatesViaCopy=true | false
Determines whether new elements are copied to other caches (true)or a remove message is sent (false). Default is true.
l asynchronousReplicationIntervalMillis=[number of ms]
The asynchronous replicator runs at a set interval of milliseconds. The default is 1000 and the minimum is 10. This property is only applicable if replicateAsynchronously=true.
Cache Bootstrap Class Name:
Specifies a BootstrapCacheLoader factory that the cache can call on initialization to prepopulate itself. The RMIBootstrapCacheLoader bootstraps caches in clusters where RMICacheReplicator s are used.
Properties Separator:
The character entered here is used to separate the list of properties listed in the field below.
Axway API Gateway 7.5.2
Policy Developer Guide 262
7 Environment configuration
Properties:
The properties listed here are used to initialize the RMIBootstrapCacheLoaderFactory. The following properties are recognized:
l bootstrapAsynchronously=true | false
Determines whether the bootstrap happens in the background after the cache has started (true), or if bootstrapping must complete before the cache is made available (false). Default is true.
l maximumChunkSizeBytes=[integer]
Caches can potentially grow larger than the memory limits on the JVM. This property enables the bootstrapper to fetch elements in chunks. The default chunk size is 5000000 (5 MB).
Distributed cache settings
In a distributed cache, there is no master cache controlling all caches in the group. Instead, each cache is a peer in the group and needs to know where all the other peers in the group are located. Peer Discovery and Peer Listeners are two essential parts of any distributed cache system.
Edit distributed cache settings
You can configure distributed cache settings by selecting the Environment Configuration > Server Settings node in the Policy Studio tree, and clicking General > Cache. Alternatively, you can access these settings in the Policy Studio main menu by selecting Tasks > Manage Gateway
Settings. You can configure the following fields:
Peer Provider Class:
By default, the built-in peer discovery class factory is used:
net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory
Properties Separator:
Specify the token used as the separator for the list of properties in the next field.
Properties:
The properties listed specify whether the peer discovery mechanism is automatic or manual. If the automatic mechanism is used, each peer uses TCP multicast to establish and maintain a multicast group. This is the default option because it requires minimal configuration and peers can be automatically added and removed from the group. Each peer pings the group every second. If a peer has not pinged any of the other peers after 5 seconds, it is dropped from the group, while a new peer is admitted to the group if it starts pinging the other peers. To use automatic peer discovery, ensure that the peerDiscovery setting is set to automatic. You can specify the multicast address and port using the multicastGroupAddress and multicastGroupPort settings. You can specify the time to live for multicast datagrams using the timeToLive setting. Axway API Gateway 7.5.2
Policy Developer Guide 263
7 Environment configuration
Alternatively, you can configure a manual peer discovery mechanism, whereby each peer definitively lists the peers it wants to communicate with. This should only be used in networks where there are problems propagating multicast datagrams. To use a manual peer discovery mechanism, ensure the peerDiscovery setting is set to manual. The list of RMI URLs of the other peers in the group must also be specified, for example:
rmiUrls=//server2:40001/sampleCache1|//server2:40001/sampleCache2
Peer Listener Class:
The peer listener class specified is responsible for listening for messages from peers in the group. Properties Separator:
Specify the token used to separate the list of properties.
Properties:
The properties entered configure the way the listener behaves. Valid properties are as follows:
l hostname (optional)
Host name of the machine on which the listener is listening. Note
By default, this is set to localhost, which maps to the local loopback address of 127.0.0.1, which is not addressable from another machine on the network. If you intend this cache to be used over the network, you should change this address to the IP address of the network interface on which the listener is listening.
l port (mandatory)
Specify the port on which the listener is listening, which by default is 4001. l socketTimeoutMillis (optional)
Enter the number of seconds that client sockets wait when sending messages to this listener until they give up. The default is 2000 ms.
Notify replicators of removal of items during refresh:
A server refresh automatically purges all items from the cache (for example, when configuration updates are deployed to the API Gateway). If this check box is selected, the contents of each peer in the group are also purged. This avoids a situation where a single peer is refreshed (and has its contents purged), but the other peers in the group are not purged. If this option is not selected, the refreshed peer attempts to bootstrap itself to the other peers in the group, resulting in the cache items becoming replicated in the refreshed cache. This effectively negates the effect of the server refresh and may result in inconsistent behavior. Distributed caching example
This example describes how to configure Ehcache for three API Gateways:
l You have three API Gateway servers and two distributed caches.
l Each API Gateway server shares its cache with the other two servers.
Axway API Gateway 7.5.2
Policy Developer Guide 264
7 Environment configuration
Step 1 – Change Ehcache settings in Policy Studio
In Policy Studio, select the Environment Configuration > Server Settings node in the Policy Studio tree, and click General > Cache. Edit the peer provider properties as follows:
peerDiscovery=manual,timeToLive=1,rmiUrls=${env.cache.rmiURL}
Edit the peer listener properties as follows:
hostName=${env.cache.IP},port=40001,socketTimeoutMillis=120000
Step 2 – Configure envSettings.props for each API
Gateway server
Add the following settings to the envSettings.props file for each API Gateway server.
envSettings.props API Gateway 1
env.cache.IP=10.0.0.1
env.cache.rmiURL=//10.0.0.2:40001/Cache1|//10.0.0.3:40001/Cache1|//10.0.0.2:40001/Ca
che2|//10.0.0.3:40001/Cache2
envSettings.props API Gateway 2
env.cache.IP=10.0.0.2
env.cache.rmiURL=//10.0.0.1:40001/Cache1|//10.0.0.3:40001/Cache1|//10.0.0.1:40001/Ca
che2|//10.0.0.3:40001/Cache2
envSettings.props API Gateway 3
env.cache.IP=10.0.0.3
env.cache.rmiURL=//10.0.0.2:40001/Cache1|//10.0.0.1:40001/Cache1|//10.0.0.2:40001/Ca
che2|//10.0.0.1:40001/Cache2
Example of caching response messages
This simple example shows how to construct a policy that caches responses from the service. It uses the request body to identify identical successive requests. If the API Gateway receives two successive requests with an identical message body, it returns the corresponding response from the cache instead of routing the request to the service. The following diagram illustrates the complete policy:
Axway API Gateway 7.5.2
Policy Developer Guide 265
7 Environment configuration
The logic of the policy is summarized as follows:
1. The purpose of the first filter is to configure what part of the request you want to use to identify unique requests. This example uses the request body as the unique key, which is then used to look up the appropriate response message from the cache. 2. The second filter looks up the request body in the response cache to see if it contains the request body. If it does, the response message that corresponds to this request is returned to the client. 3. If it does not, the request is routed to the service, which processes it (by connecting to a database over the network and running a SQL statement) and returns a response to the API Gateway.
4. The API Gateway then returns the response to the client and caches it in the response cache. 5. When the next identical request is received by the API Gateway, the corresponding response is located in the responses cache and returned immediately to the client. You must configure the following caching filters to achieve this policy. For convenience, the routing filters are not included in this example because the configuration options depend on your target service. Create Key
This filter is used to decide what part of the request is used for a request to be considered unique. Different parts of the request can be identified internally using message attributes (for example, content.body contains the request body). The following fields must be configured for this filter:
l Name: Use request body to create unique key
l Attribute Name: content.body
l Output attribute name: message.key
Axway API Gateway 7.5.2
Policy Developer Guide 266
7 Environment configuration
Is Cached?
This filter looks up the cache to see if a response has been stored for the current request. It looks up the cache using the message.key attribute by default. The message.key attribute contains a hash of the request message, and can be used as the key for objects in the cache. If the key is found in the cache, the value of the key (cached response for this request) is written to the content.body attribute, which can be returned to the client using the Reflect filter. You must configure the following fields:
l Name: Is a response for this request already cached?
l Cache containing key: Response Cache (assuming you have created a cache of this name)
l Attribute Containing Key: message.key
l Overwrite attribute name if found: content.body
Reflect
If the Is Cached? filter passes, it retrieves the response from the cache and stores it in the content.body message attribute. The Reflect filter is used to return the cached response to the client.
Routing
If a response for this request could not be located in the cache, the API Gateway routes the request to the service, and waits for a response. For more details on how to route messages, see Get started with routing configuration on page 770.
Cache Attribute
When the response has been received from the service, it should be cached for future use. The Cache Attribute filter is used to configure the key used to look up the cache and which aspect of the response message is stored as the key value in the cache.
Note
This example specifies the value of the content.body attribute to cache. Because this filter is configured after the routing filters, this attribute contains the response message. The value entered in the Attribute Key field should match that entered in the Attribute
containing key field in the Is Cached? filter. You must configure the following fields:
l Name: Cache response body
l Cache to use: Response Cache
l Attribute key: message.key
l Attribute name to store: content.body
Axway API Gateway 7.5.2
Policy Developer Guide 267
7 Environment configuration
Further information
For more information on these filters, see the following topics:
Filter
Topic
Create Key
Create key on page 590
Is Cached?
Check if attribute is cached on page 591
Cache Attribute
Cache attribute on page 589
Remove Cached Attribute
Remove cached attribute on page 592
Cross-Origin Resource Sharing
Overview
Cross-Origin Resource Sharing (CORS) enables client-side code running in a browser in a particular domain to access resources hosted in another domain in a secure manner. Cross-origin requests are typically not permitted by browsers, and CORS provides a framework in which cross-domain requests are treated as same-domain requests. For example, using CORS, JavaScript embedded in a web page can make an HTTP XMLHttpRequest to a different domain. This is used to send an HTTP or HTTPS request to a web server, and to load the server response data back into the script. The following diagram shows an example CORS architecture:
This example is described as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 268
7 Environment configuration
1. A user browses to the following URL:
http://client.cors-api.appspot.com
2. The client page displayed on the left contains JavaScript that attempts to access resources in Domain A ( http://client.cors-api.appspot.com), and in Domain B ( http://item-a16823:8080).
3. Attempts by the browser to access resources in Domain A are granted because Domain A is the same domain in which the JavaScript code is running. 4. When the browser attempts to access resources in Domain B, it must use the CORS protocol because Domain B is in a different domain than that in which the JavaScript code is running. In this way, CORS enables client JavaScript code running in the browser in Domain A to access resources in Domain B.
The CORS standard provides CORS HTTP headers that enable servers to serve resources to permitted origin domains. Browsers support these CORS HTTP headers and enforce their restrictions. Browsers can also send preflight CORS requests to retrieve supported methods from the server using an HTTP OPTIONS method. Then on approval from the server, the browser client can send the request with the appropriate HTTP request method. CORS request headers
The CORS HTTP request headers are as follows:
l Origin
l Access-Control-Request-Method (preflight only)
l Access-Control-Request-Headers (preflight only)
CORS response headers
The CORS HTTP response headers are as follows:
l Access-Control-Allow-Origin
l Access-Control-Allow-Credentials
l Access-Control-Expose-Headers
l Access-Control-Max-Age (preflight only)
l Access-Control-Allow-Methods (preflight only)
l Access-Control-Allow-Headers (preflight only)
Add a CORS profile
To enable CORS support in API Gateway, you must first add a CORS profile in Policy Studio:
Axway API Gateway 7.5.2
Policy Developer Guide 269
7 Environment configuration
1. In the Policy Studio tree, select Environment Configuration > Libraries > CORS Profiles.
2. Right-click and select Add a CORS Profile, and configure the settings on the following tabs. General
Configure the following general settings:
l Name:
Unique name of the CORS profile. Defaults to Cross Origin Resource Sharing.
l Enable CORS:
Specifies whether CORS processing is enabled for the profile. Enabled by default.
Origins
The Origins table enables you to configure the list of origins that are allowed to access resources configured with this CORS profile, or exposed by a specific HTTP service. Click Add at the bottom right to add an origin.
You can specify origins using the following values:
l * (permits all values supplied in the CORS Origin header)
l Domain (for example, http://client.corsapi.appspot.com)
l Wildcarded value (for example, http://*.appspot.com or http://client.corsapi.appspot.com:*)
Allowed Headers
The Allowed Headers table enables you to configure the list of HTTP headers that are permitted when requesting a resource exposed by this CORS profile or HTTP service. The list of headers is defined by the value of the Access-Control-Request-Headers CORS header. Click the Add button at the bottom right of the window to add an allowed header to the table.
Note
The list of allowed headers is checked only during a CORS preflight OPTIONS request, which can be sent before access to the resource is granted.
Exposed Headers
The Exposed Headers table enables you configure the list of CORS HTTP response headers that are exposed to the client. Click the Add button at the bottom right of the window to add an exposed header to the table.
You can specify the list of CORS headers that are exposed to the client, in response to a resource exposed by this profile or HTTP service. You do not need to include the following simple HTTP response headers:
Axway API Gateway 7.5.2
Policy Developer Guide 270
7 Environment configuration
l Cache-Control
l Content-Type
l Content-Language
l Expires
l Last-Modified
l Pragma
Credentials Support
The Support credentials setting specifies whether resources using this CORS profile or HTTP service support user credentials. When this option is selected, the Access-Control-AllowCredentials CORS header is sent in the response, with a value of true. This setting is not selected by default.
Preflight Results Cache
The Max. age (seconds) setting specifies how long the results of a CORS preflight OPTIONS request can be stored in the client preflight result cache. When this setting is configured, the Access-Control-Max-Age CORS header is sent in the response.
Configure CORS for HTTP services
You can also configure a CORS profile at the HTTP service level. This means that the settings configured for the profile are also applied to any child resolvers of this HTTP service. For example, this may be useful when using a third-party load balancer, and you need to configure a CORS profile for the default API Portal HTTP service, and specify the load balancer address as an origin. To configure CORS at the HTTP service level, perform the following steps:
1. In the Policy Studio tree, select an HTTP service (for example, Environment Configuration > Listeners > API Gateway > Default Services).
2. Right-click, and select Edit to display the HTTP Services dialog.
3. Select the CORS tab, and click the browse button to select a preconfigured CORS profile. By default, no profile is selected, which means that CORS is disabled.
4. In the Select CORS Profile dialog, if no profiles have already been configured, right-click CORS Profiles, and select Add a CORS Profile. You can also right-click an existing profile, and select Edit to update its settings. For details on CORS settings, see Add a CORS profile on Axway API Gateway 7.5.2
Policy Developer Guide 271
7 Environment configuration
page 269.
For more details on HTTP services, see Configure HTTP services on page 290.
Configure CORS for relative paths
By default, the CORS profile set at the parent HTTP service level is used for all child resolvers of the HTTP service. However, you can override this at the relative path level as follows:
1. In the Policy Studio tree, select a list of relative paths (for example, Environment
Configuration > Listeners > API Gateway> Default Services > Paths).
2. In the Resolvers window on the right, right-click a resolver, and select Edit to display the dialog. 3. Select the CORS tab, and in the CORS Usage field, select Override CORS using the
following profile. By default, no CORS profile is selected, and the parent settings are used.
Note
Relative paths can act as HTTP services, and can accommodate child resolvers. This means that when a relative path has children, and has a CORS profile configured, by default, the children use the parent profile (unless a child overrides it).
4. In the CORS Profile field, click the browse button to select a preconfigured CORS profile. 5. If no CORS profiles have already been configured, right-click CORS Profiles, and select Add a
CORS Profile. You can also right-click an existing profile, and select Edit to update its settings. For details on CORS settings, see Add a CORS profile on page 269.
Note
Similarly, you can also override CORS for the following relative path resolvers:
l Static Content Providers
l Static File Providers
l Servlet Application
Axway API Gateway 7.5.2
Policy Developer Guide 272
7 Environment configuration
For more details on relative paths and resolvers, see Configure relative paths on page 308.
Key Property Store
Overview
A Key Property Store (KPS) is a table of data referenced by policies running on an API Gateway. Data in a KPS table is assumed to be read frequently and seldom written, and can be changed without incurring an API Gateway service outage. KPS tables are shared across an API Gateway group. Data can be stored in one of the following locations:
l External Apache Cassandra database—data can be distributed across multiple nodes to provide high availability (default).
l Relational database accessible to all API Gateways in the group
l JSON files on the local file system (deprecated in this release).
A KPS is typically used to store property values used in policies on an API Gateway. KPS data is injected into policies using selectors created in Policy Studio. Selectors are evaluated and expanded dynamically at runtime. For example, a KPS table contains authorization tokens for different users. A policy looks up the token for the current user, and inserts it into an HTTP request.
Caution
Do not edit the default KPS tables in Policy Studio unless under strict supervision from Axway Support. This includes the API Server, OAuth, or API Portal KPS tables available under Environment Configuration > Key Property Stores.
KPS tables and collections
KPS tables are organized into collections. The tables in a collection typically have a relationship to each other. For example, the OAuth collection contains a set of tables that store all OAuth-related data. Every KPS table is assigned an alias so that it can be easily referred to in a policy or a REST request.
Column
Type
Description
email
String
User email address. This is the primary key used to identify a row in the table. password
String
User password. This confidential data is encrypted.
firstName
String
User first name.
lastName
String
User surname.
Axway API Gateway 7.5.2
Policy Developer Guide 273
7 Environment configuration
Column
Type
Description
age
Integer
User age.
Enter data in a KPS table
You can enter data in a KPS table using the API Gateway Manager web console for viewing and modifying data. This is available in API Gateway Manager under Settings > Key Property Stores. The kpsadmin command-line tool also supports data entry in addition to other administrative functions. KPS data can also be read and written by remote programmatic clients using the KPS REST interface.
New values for encrypted fields are always transmitted to the server in the clear. For security, always use HTTPS when accessing KPS over its REST API (this is the default).
The following example shows some simple table data that has been entered in API Gateway Manager, and which follows the example structure in KPS tables and collections on page 273:
email
password
firstName
lastName
age
[email protected]
*****
John
Doe
21
[email protected]
*****
Joe
Bloggs
42
[email protected]
*****
Jean
Dupont
33
In this example, the email column is the primary key. You can use this to look up and uniquely identify a row using a selector expression. For example, the following selector expression evaluates to John:
${kps.customers["[email protected]"].firstName}
The following selector expression evaluates to 42:
${kps.customers["[email protected]"].age}
For more details on selectors, see Select configuration values at runtime on page 854.
KPS data sources
A KPS provides a consistent interface to data that can be stored in different data sources. API Gateway supports the following KPS data sources:
l External Apache Cassandra database ( default): Used across an API Gateway group to provide high availability in a production environment.
Axway API Gateway 7.5.2
Policy Developer Guide 274
7 Environment configuration
l Relational Database: Enables you to use your existing database (for example, Oracle, Microsoft SQL Server, IBM DB2, or MySQL). The following approaches to data storage are supported:
o Shared storage—data for multiple KPS tables is stored in a single dedicated database table. This is the recommended approach.
o Per-table storage—each KPS table is backed by a single database table.
l JSON files on the local file system: Suited to single API Gateway deployments. In a multiAPI Gateway scenario, file replication or a shared disk is required to ensure all API Gateways use the same data.
Note
If a file-based KPS table is shared across API Gateways, the API Gateways must be restarted after data has changed. File-based KPS is deprecated in this release.
Add a KPS collection
A KPS collection is a group of KPS tables. To add a KPS collection, perform the following steps: The newly created KPS collection is displayed on the window on the right.
1. In the Policy Studio tree, right-click Environment Configuration > Key Property Stores, and select Add KPS Collection.
2. Complete the following fields in the Add KPS Collection dialog:
l Name: Enter the KPS name (for example, CustomerCollection).
l Description: Enter a text description of your KPS collection.
l Alias prefix: Leave this field blank.
l Default data source: Select one of the following from the list:
o File
o Cassandra
o SQL Database
Defaults to Cassandra.
Edit a KPS collection
To edit a KPS collection, perform the following steps:
1. In the main Policy Studio tree, select the KPS collection to edit under Environment
Configuration > Key Property Stores.
2. Click the Properties tab.
3. You can edit the Name, Description, or Alias prefix for the KPS collection as required.
4. To change the Default data source, click the browse button to display a tree of data sources, and select a new default data source from the tree.
Axway API Gateway 7.5.2
Policy Developer Guide 275
7 Environment configuration
5. You can also specify a cache for storage and retrieval of selector results. This improves selector read performance for storage backends such as databases. In the Cache field, click the browse button to display a tree of caches, and select a cache. Only local caches are supported.
6. You can add, edit, or delete KPS collection data sources on the Data Sources tab. For more information, see the following sections.
7. Click Save at the top right to save your changes.
Add a Cassandra data store
To add an Cassandra database data store to a selected KPS collection, perform the following steps:
1. On the Data Sources tab, select Add > Add Cassandra at the bottom right.
2. Complete the following fields in the Add Cassandra Data Source dialog:
l Name: Enter the KPS name (for example, Customer Cassandra Data
Source).
l Description: Enter a text description of your SQL database data source.
l Read Consistency Level: Select the consistency level from the list. Defaults to ONE.
l Write Consistency Level: Select the consistency level from the list. Defaults to ONE.
For more details, see https://docs.datastax.com/en/cassandra_
win/2.2/cassandra/dml/dmlConfigConsistency.html.
3. Click OK.
Add a database data store
To add an SQL database data store to a selected KPS collection, perform the following steps:
1. On the Data Sources tab, select Add > Add Database at the bottom right.
2. Complete the following fields in the Add File Data Source dialog:
l Name: Enter the KPS name (for example, Customer DB Data Source).
l Description: Enter a text description of your SQL database data source.
l Database Connection: Click the button on the right, select a database connection in the dialog (for example, Default Database Connection), and click OK . You can add more database connections to the list by right-clicking Environment
Configuration > External Connections > Database Connections in the Policy Studio tree, and selecting Add a Database Connection.
3. Click OK.
Add a file data store
To add a file-based data store to a selected KPS collection, perform the following steps:
Axway API Gateway 7.5.2
Policy Developer Guide 276
7 Environment configuration
1. On the Data Sources tab, select Add > Add File at the bottom right.
2. Complete the following fields in the Add File Data Source dialog:
l Name: Enter the KPS name (for example, Customer File Data Source).
l Description: Enter a text description of your file data source.
l Directory Path: Enter the full directory path (for example, c:\kpsdata). Each table in the collection has its own JSON file in this directory.
3. Click OK.
Add a KPS table
To add a KPS table to a KPS collection, perform the following steps: The newly created KPS table is displayed on the window on the right.
1. In the main Policy Studio tree, right-click a KPS collection (for example CustomerCollection), and select Add Table.
2. Complete the following fields in the Add KPS Table dialog:
l Name: Enter the KPS name (for example, Customers).
l Description: Enter a text description of your KPS.
l Aliases: Click Add, and enter an alias used to identify your KPS (for example, customers), and click OK. Every KPS must have at least one alias.
3. Click OK.
Define the KPS table structure
To define the KPS table structure, perform the following steps:
1. In the main Policy Studio tree, select a KPS table (for example Customers), and click the Structure tab.
2. Click Add, and complete the following fields in the Add Property dialog:
l Name: Enter the name of the table column (for example, email).
l Type: Select the data type from the list (for example, java.lang.String).
l Key: For java.util.Map types, select the key type from the list (for example, java.lang.Integer).
l Value: For java.util.Map and java.util.List types, select the value type from the list (for example, java.lang.Boolean).
3. Click OK . The newly created KPS table column is added to the Structure tab.
4. Select Primary Key to make a field the primary key for the table.
5. Select Autogenerated to auto-generate a field in the KPS data source.
Axway API Gateway 7.5.2
Policy Developer Guide 277
7 Environment configuration
6. Select Encrypted to encrypt a field in the KPS data source.
7. Select Indexed to index a field in the KPS data source.
8. Repeat the preceding steps to add more table columns.
9. At the bottom, enter names of one or more properties used to look up this table from a selector (for example, firstName,surname). If none are specified, selectors can access the table using the primary key.
10. Click Save at the top right to save your changes.
Further information
For more details on Key Property Stores, see the API Gateway Key Property Store User Guide.
For more details on installing and configuring Apache Cassandra, see the API Gateway Installation Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 278
API Gateway instances
8
This section describes how to configure API Gateway instances.
Configure API Gateway instances
279
Configure remote host settings
283
Configure HTTP watchdog
288
Configure HTTP services
290
Packet sniffers
301
Configure conditions for HTTP interfaces
303
Configure a transparent proxy
305
Configure relative paths
308
Configure WebSocket connections
320
Configure virtual hosts
328
Configure SMTP services
331
Configure a file transfer service
347
Configure an FTP poller
354
Configure a directory scanner
358
Configure a POP client
361
TIBCO integration
362
TIBCO Rendezvous listener
362
Configure Amazon SQS queue listener
363
Cryptographic acceleration
367
Cryptographic acceleration conversation: request-response
369
Configure API Gateway instances
Overview
This topic shows how to configure a running instance of the API Gateway. You can configure the options described in the following sections on the API Gateway instance in the Policy Studio tree (for example, under Environment Configuration > Listeners > API Gateway).
Axway API Gateway 7.5.2
Policy Developer Guide 279
8 API Gateway instances
Add remote hosts
Remote host settings configure the way in which the API Gateway routes to another host machine. For example, if a destination server may not fully support HTTP 1.1, you can configure Remote
Host settings for the server to optimize the way in which the API Gateway sends messages to it. Similarly, if the server requires an exceptionally long timeout, you can configure this in the Remote
Host settings. For more details, see Configure remote host settings on page 283.
Add HTTP services
You can add a container for HTTP-related services, including HTTP and HTTPS Interfaces, Directory Scanners, Static Content Providers, Servlet Applications, and Packet Sniffers.
HTTP services act as a container for all HTTP-related interfaces to the API Gateway's core messaging pipeline. You can configure HTTP and HTTPS interfaces to accept plain HTTP and SSL messages respectively. A relative path interface is available to map requests received on a particular URI or path to a specific policy. The Static Content Provider interface can retrieve static files from a specified directory, while the Servlet Application enables you to deploy servlets under the service. Finally, the Packet Sniffer interface can read packets directly of the network interface, assemble them into HTTP messages, and dispatch them to a particular policy. Configure HTTP services on page 290 explains how to configure the available HTTP interfaces. Add SMTP services
Simple Mail Transfer Protocol (SMTP) support enables the API Gateway to receive email and to act as a mail relay. The API Gateway can accept email messages using the SMTP protocol, and forward them to a mail server. You can also configure optional policies for specific SMTP commands (for example, HELO/EHLO and AUTH).
Configure SMTP services on page 331 explains how to configure SMTP services, interfaces, and handler policies. Add file transfer services
You can configure the API Gateway to listen for remote clients that connect to it as a file server. This enables the API Gateway to apply configured policies on transferred files (for example, for schema validation, threat detection or prevention, routing, and so on). The API Gateway supports File Transfer Protocol (FTP), FTP over SSL (FTPS), and Secure Shell FTP (SFTP). Configure a file transfer service on page 347 explains how to configure the API Gateway as a file transfer service. Axway API Gateway 7.5.2
Policy Developer Guide 280
8 API Gateway instances
Add policy execution scheduling
Policy execution scheduling enables you to schedule the execution of any policy on a specified date and time in a recurring manner. The API Gateway provides a preconfigured library of schedules to select from. You can also add your own schedules to the library. Policy execution scheduling on page 256 explains how to add a policy execution schedule, and how to add schedules. Configure JMS messaging system
You can configure the API Gateway to read JMS messages from a JMS queue or topic, run them through a policy, and then route onwards to a web service or JMS queue or topic.
The API Gateway can consume a JMS queue or topic as a means of passing XML messages to its core message processing pipeline. When the message has entered the pipeline, it can be validated against all authentication, authorization, and content-based message filters. Having passed all configured message filters, it can be routed to a destination web service over HTTP, or it can be dropped back on to a JMS queue or topic using the Messaging System connection filter. For more details, see Configure messaging services on page 161. Add Amazon SQS queue listener
The Amazon SQS Queue Listener enables you to poll an Amazon SQS queue for messages at a specified rate. When messages are retrieved from the queue, they can be passed to a specified policy for processing. For more details, see Configure Amazon SQS queue listener on page 363.
Add FTP poller
The FTP Poller enables you to query and retrieve files by polling a remote file server. When files are retrieved, they can be passed into the API Gateway core message pipeline for processing. For example, this is useful in cases where an external application drops files on to a remote file server, which can then be validated, modified, or routed on over HTTP or JMS by the API Gateway. For more details, see Configure an FTP poller on page 354.
Add directory scanner
The Directory Scanner reads XML files from a specified directory and dispatches them to a selected policy. This enables you to search a local directory for XML files, which can then be fed into a security policy for validation. Typically, XML files are transferred by FTP or saved to the file system Axway API Gateway 7.5.2
Policy Developer Guide 281
8 API Gateway instances
by another application. The API Gateway can then pick these files up, run the full array of authentication, authorization, and content-based filters on the messages, and then route them over HTTP or JMS to a back-end system. For more details, see Configure a directory scanner on page 358.
Add POP client
The POP Client enables you to poll a POP mail server to read email messages from it, and pass them into a policy for processing. For more details, see Configure a POP client on page 361.
Configure TIBCO
You can configure a TIBCO Rendezvous listener for real-time messaging. For more details, see TIBCO Rendezvous listener on page 362.
API Gateway settings
You can configure per-instance global configuration settings by clicking the Environment
Configuration > Server Settings node in the Policy Studio tree. For example, these include settings for timeouts, caches, logging, monitoring, security, and so on. For more details on configuring API Gateway instance settings, see the API Gateway Administrator Guide.
Cryptographic acceleration
The API Gateway can leverage the OpenSSL Engine API to offload complex cryptographic operations (for example, RSA and DSA) to a hardware-based cryptographic accelerator, and to act as an extra layer of security when storing private keys on a Hardware Security Module (HSM).
The API Gateway uses OpenSSL to perform cryptographic operations, such as encryption and decryption, signature generation and validation, and SSL tunneling. OpenSSL exposes an Engine API, which enables you to plug in alternative implementations of some or all of the cryptographic operations implemented by OpenSSL. OpenSSL can, when configured appropriately, call the engine's implementation of these operations instead of its own. For more information on configuring API Gateway to use an OpenSSL engine, see Cryptographic acceleration on page 367.
Axway API Gateway 7.5.2
Policy Developer Guide 282
8 API Gateway instances
Configure remote host settings
Overview
You can use the Remote Host Settings to configure the way in which API Gateway connects to a specific external server or routing destination. For example, typical use cases for configuring remote hosts with API Gateway are as follows:
l Allowing API Gateway to send HTTP 1.1 requests to a destination server when that server supports HTTP 1.1.
l Resolving inconsistencies in the way the destination server supports HTTP.
l Mapping a host name to a specific IP address or addresses (for example, if a DNS server is unreliable or unavailable). l Setting the timeout, session cache size, input/output buffer size, and other connection-specific settings for a destination server (for example, if the destination server is particularly slow, you can set a longer timeout).
l Stop accepting inbound connections on the HTTP interface when API Gateway loses connectivity to the remote host. l Set timeouts for incoming connections, for example, to configure long polling. For more information, see Configure an incoming remote host on page 288. You can add remote hosts per-instance to the API Gateway instance in the Policy Studio tree. For example, select Environment Configuration > Listeners > API Gateway >, right-click this instance, and select Add Remote Host. The tabs in the Remote Host Settings configuration window are described in the following sections.
General settings
You can configure the following settings on the General tab:
Host Alias:
The human readable alias name for the remote host (for example, StockQuote Host). This setting is required.
Host Name:
The host name or IP address of the remote host to connect to (for example stockquote.com). If the host name entered in a Static Router filter matches this host name, the connection-specific settings configured on the Remote Host dialog are used when connecting to this host. This also includes any IP addresses listed on the Addresses and Load Balancing tab, which override the default network DNS server mappings, if configured. This setting is required.
Port:
The TCP port on the remote host to connect to. Defaults to 80.
Axway API Gateway 7.5.2
Policy Developer Guide 283
8 API Gateway instances
Maximum Connections:
The maximum number of connections to open to a remote host. If the maximum number of connections has already been established, the API Gateway instance waits for a connection to drop or become idle before making another request. The default maximum is 128 connections.
Allow HTTP 1.1:
The API Gateway uses HTTP 1.0 by default to send requests to a remote host. This prevents any anomalies if the destination server does not fully support HTTP 1.1. If the API Gateway is routing on to a remote host that fully supports HTTP 1.1, you can use this setting to enable API Gateway to use HTTP 1.1.
Include Content Length in Request:
When this option is selected, the API Gateway includes the Content-Length HTTP header in all requests to this remote host.
Include Content Length in Response:
When this option is selected, if the API Gateway receives a response from this remote host that contains a Content-Length HTTP header, it returns this length to the client.
Send Server Name Indication TLS extension to server:
Adds a field to outbound TLS/SSL calls that shows the name that the client used to connect. This can be useful if the server handles several different domains, and needs to present different certificates depending on the name the client used to connect. For example, this is required by some cloud-based services such as Amazon CloudFront. This setting is not selected by default.
Note
To send the SNI extension, you must ensure that the Verify server's certificate
matches requested hostname setting is also selected. In addition, the Port setting must be the port that you are connecting to the server with (for example, 443 is the default port for SSL).
Verify server's certificate matches requested hostname:
Ensures that the certificate presented by the server matches the name of the remote host being connected to. This prevents host spoofing and man-in-the-middle attacks. This setting is selected by default. Address and load balancing settings
You can configure the following settings on the Addresses and Load Balancing tab:
Addresses to use instead of DNS lookup:
You can add a list of IP addresses that the API Gateway uses instead of attempting a DNS lookup on the host name provided. This is useful in cases where a DNS server is not available or is unreliable. By default, connection attempts are made to the listed IP addresses on a round-robin basis.
For example, if a Static Router filter is configured to route to www.webservice.com, it first checks if any remote hosts have been configured with a Host Name entry matching www.webservice.com. If it finds a Remote Host with matching Host Name , it resolves the host name to the IP addresses listed here. In addition, it uses all the connection-specific settings Axway API Gateway 7.5.2
Policy Developer Guide 284
8 API Gateway instances
configured on the Remote Host dialog when routing messages to these IP addresses. If it cannot find a matching host, the Static Router filter uses whatever DNS server has been configured for the network on which the API Gateway is running. To add a list of IP addresses for a remote host, perform the following steps:
1. In the Addresses to use instead of DNS lookup box, select a priority group (for example, Highest Priority).
2. Click Add.
3. Enter an IP address or server name in the Configure IP Address dialog.
4. Click OK.
5. Repeat these steps to add more IP addresses as appropriate.
Load balancing:
The Load Balancing Algorithm drop-down box enables you to specify whether load balancing is performed on a simple round-robin basis or weighted by response time. Simple Round Robin is the default algorithm. Connection attempts are made to the listed IP addresses on a round-robin basis in each priority group. The Weighted by response time algorithm compares the request/reply response times for the server address in each priority group. This is the simplest way of estimating the relative load of the address. This algorithm works as follows:
1. The address with the least response time is selected to send the next message to.
2. If the address fails to send the message, it ignores that address for a period of time and selects another address in the same way.
3. If all addresses in a given group fail to accept a connection, addresses in the next group in ascending order of priority are used in the same way.
4. Only when all addresses in all priorities have failed to accept connections is delivery of the message abandoned, and an error raised.
The response times used by this algorithm decline over time. You can specify the rate of exponential decline by specifying a Period to wait before response time is halved. The default is 10,000 ms (10 sec). This enables addresses that were heavily loaded for a period of time to eventually resume accepting messages after the load subsides. For example, server A takes 100 ms to reply, and the other servers in the same priority group reply in 25 ms. A Period to wait before response time is halved of 10,000 ms (10 sec) means that after 20 seconds server A is retried along with the other servers. In this case, the response time has been halved twice (100 ms / 2 / 2 = 25 ms).
Advanced settings
The options available on the Advanced tab are used when creating sockets for connecting to the remote host. Default values are provided for all fields, which should only be modified under advice from the Axway Support.
You can configure the following configuration options on the Advanced tab:
Axway API Gateway 7.5.2
Policy Developer Guide 285
8 API Gateway instances
Connection Timeout:
If a connection to this remote host is not established within the time set in this field, the connection times out and the connection fails. Defaults to 30000 milliseconds (30 seconds). Active Timeout:
When the API Gateway receives a large HTTP request, it reads the request off the network when it becomes available. If the time between reading successive blocks of data exceeds the Active
Timeout, the API Gateway closes the connection. This prevents a remote host from closing the connection while sending data. Defaults to 30000 milliseconds (30 seconds). For example, the remote host's network connection is pulled out of the machine while sending data to the API Gateway. When the API Gateway has read all the available data off the network, it waits the Active Timeout period before closing the connection. Transaction Timeout (ms):
A configurable transaction timeout that detects slow HTTP attacks (slow header write, slow body write, slow read) and rejects any transaction that keeps the worker threads occupied for an excessive amount of time. The default value is 240000 milliseconds.
Max Received Bytes:
The maximum number of bytes received in a transaction. This is a configurable maximum length for the received data on transactions that API Gateway can handle. This setting limits the entire amount of data received over the link, regardless of whether it consists of body, headers, or request line. The default value is 10 MB (10485760 bytes).
Max Sent Bytes:
The maximum number of bytes sent in a transaction. This is a configurable maximum length for the transmitted data on transactions that API Gateway can handle. This setting limits the entire amount of data sent over the link, regardless of whether it consists of body, headers, or request line. The default value is 10 MB (10485760 bytes).
Idle Timeout:
The API Gateway supports HTTP 1.1 persistent connections. The Idle Timeout is the time that API Gateway waits after sending a message over a persistent connection to the remote host before it closes the connection. Defaults to 15000 milliseconds (15 seconds). Typically, the remote host tells the API Gateway that it wants to use a persistent connection. The API Gateway acknowledges this, and keeps the connection open for a specified period of time after sending the message to the host. If the connection is not reused by within the Idle Timeout period, the API Gateway closes the connection. Input Buffer Size:
The maximum amount of memory allocated to each request. The default value is 8192 bytes.
Output Buffer Size:
The maximum amount of memory allocated to each response. The default value is 8192 bytes.
Cache addresses for (ms):
The period of time to cache addressing information after it has been received from the naming service (for example, DNS). The default value is 300000 milliseconds.
Axway API Gateway 7.5.2
Policy Developer Guide 286
8 API Gateway instances
SSL Session Cache Size:
Specifies the size of the SSL session cache for connections to the remote host. This controls the number of idle SSL sessions that can be kept in memory. Defaults to 32. If there are more than 32 simultaneous SSL sessions, this does not prevent another SSL connection from being established, but means that no more SSL sessions are cached. A cache size of 0 means no cache, and no outbound SSL connections are cached.
Tip
You can use this setting to improve performance because it caches the slowest part of establishing the SSL connection. A new connection d oes not need to go through full authentication if it finds its target in the cache.
At DEBUG level or higher, the API Gateway outputs trace when an entry goes into the cache, for example:
DEBUG
09:09:12:953 [0d50] cache SSL session 11AA3894 to support.acme.com:443
If the cache is full, the output is as follows:
DEBUG
09:09:12:953 [0d50] enough cached SSL sessions 11AA3894 to
support.acme.com:443 already
Input Encodings:
Click the browse button to specify the HTTP content encodings that the API Gateway can accept from peers. The available content encodings include gzip and deflate. By default, the content encodings configured the Default Settings are used. You can override this setting at the remote host and HTTP interface levels. For more details, see Compressed content encoding on page 863.
Output Encodings:
Click the browse button to specify the HTTP content encodings that the API Gateway can apply to outgoing messages. The available content encodings include gzip and deflate. By default, the content encodings configured the Default Settings are used. You can override this setting at the remote host and HTTP interface levels. For more details, see Compressed content encoding on page 863.
Include correlation ID in headers:
Specifies whether to insert the correlation ID in outbound messages. This means that an XCorrelationID header is added to the outbound message. This is a transaction ID that is attached to each message transaction that passes through API Gateway, and which is used for traffic monitoring in the API Gateway Manager web console. You can use the correlation ID to search for messages in the web console, and you can also access its value from a policy using the id message attribute. This setting is selected by default.
Configure watchdogs
You can configure an HTTP interface to shut down based on certain conditions. One such condition is dependent on the API Gateway being able to contact a particular back-end web service running on a remote host. To do this, you can configure an HTTP Watchdog for a remote host to poll the endpoint. If the endpoint cannot be reached, the HTTP interface is shut down. Axway API Gateway 7.5.2
Policy Developer Guide 287
8 API Gateway instances
To configure the API Gateway to shut down an HTTP interface based on the availability of a remote host, perform the following steps:
1. Configure an HTTP Watchdog for the remote host.
2. Configure a Requires Endpoint condition on the HTTP interface.
3. When configuring this condition, select the remote host configured in step 1 (the host with the associated Watchdog).
Note
When Load Balancing is configured as Weighted by response time, and remote host watchdogs are configured, the watch dog polling also contributes to the load balancing calculations.
For more information on adding a watchdog to a remote host, see Configure HTTP watchdog on page 288. For more information on adding conditions to an HTTP interface, see Configure conditions for HTTP interfaces on page 303. Configure an incoming remote host
A remote host is normally used to configure specific connection features for the outward connection, that is, for the connection from API Gateway to the back-end service. However, you can also configure a remote host for an incoming connection, that is, for the connection from the client to API Gateway.
To configure an incoming remote host, configure the following settings on the General tab of the remote host settings:
1. Enter incoming in the Port field.
For an incoming connection, the port is referring to the remote address of the TCP connection. Incoming connections arrive from effectively arbitrary remote ports, so this acts as a wildcard for all incoming connections.
2. Enter the IP address of the host in the Host name field, rather than the DNS name. A CIDR style netmask can be specified (for example, 192.168.0.0/24 matches any address in the 192.168.0.x range). This works on a longest-match basis if more than one network specification matches the client.
Configure HTTP watchdog
Overview
An HTTP Watchdog can be added to a Remote Host configuration in order to periodically poll the Remote Host to check its availability. For example, if the Remote Host becomes unavailable for some Axway API Gateway 7.5.2
Policy Developer Guide 288
8 API Gateway instances
reason, an HTTP interface can be brought down and can stop accepting requests. Once the Remote Host comes back online, the HTTP interface automatically starts up and starts accepting requests again.
To learn more about the reasons for shutting down an HTTP interface if certain conditions d o not hold, see Configure conditions for HTTP interfaces on page 303.
To configure an HTTP Watchdog, right-click a previously configured Remote Host in the Policy Studio tree (for example, under Environment Configuration > Listeners > API Gateway). Then select Watchdog > Add, and configure the settings in the dialog.
Configuration
Configure the following settings:
Valid HTTP Response Code Ranges:
You can use this section to specify the HTTP response codes that you can regard as proof that the Remote Host is available. For example, if a 200 OK HTTP response is received for the poll request, the Remote Host can be considered available. To specify a range of HTTP status codes, click the Add button and enter the Start and End of the range of HTTP response codes in the fields provided. An exact response code can be specified by entering the response code in both fields (for example, 200). HTTP Request for Polling:
The fields in this section enable you to configure the type and URI of the HTTP request to poll the Remote Host with. The default is the Options HTTP command with a URI of *, which is typically used to retrieve status information about the HTTP server. To use an alternative HTTP request to poll the Remote Host, select an HTTP request method from the Method, and specify the URI field.
Remote Host Polling:
The settings in this section determine when and how the HTTP Watchdog polls the Remote Host. The Poll Frequency determines how often the Watchdog is to send the polling request to the Remote Host.
By default, the Watchdog uses real HTTP requests to the Remote Host to determine its availability. In other words, if the API Gateway is sending a batch of requests to the Remote Host, it uses the response codes from these requests to decide whether or not the Remote Host is up. Therefore, the Watchdog effectively "polls" the Remote Host by sending real HTTP requests to it. To configure the Watchdog to send poll requests during periods when it is not sending requests to and receiving responses from the Remote Host, select Poll if up. In this case, the Watchdog uses real HTTP requests to poll the Remote Host as long as it sends them, but starts sending test poll requests when it is not sending HTTP requests to the Remote Host to test its availability.
Note
When a Remote Host is deemed to be down (an invalid HTTP response code was received) the Watchdog continues to poll it at the configured Poll Frequency until it comes back up again (until a valid HTTP response code is received).
Axway API Gateway 7.5.2
Policy Developer Guide 289
8 API Gateway instances
Configure HTTP services
Overview
The API Gateway uses HTTP Services to handle traffic from various HTTP-based sources. The available HTTP Services are as follows:
HTTP interfaces
HTTP interfaces d efine the ports and IP addresses on which the API Gateway instance listens for incoming requests. You can also add HTTPS interfaces to specify SSL certificates to authenticate to clients, and certificates considered trusted for establishing SSL connections with clients. Relative path
You can configure relative paths so that when a request is received on a specific path, the API Gateway instance can map it to a specific policy, or chain of policies. For more details, see Configure relative paths on page 308. Static content provider
You can use a static content provider to serve static HTTP content from a particular directory. In this case, the API Gateway instance is effectively acting as a web server. For more details, see Static content providers on page 315.
Servlet applications
The API Gateway instance can act as a servlet container, which enables you to drop servlets into the HTTP services configuration. This should only be used by developers with very specific requirements and under strict advice from the Axway Support team. For more details, see Servlet applications on page 317.
Packet sniffer
You can add a packet sniffer to intercept network packets from the client, assemble them into complete HTTP messages, and log these messages to an audit trail. Because the packet sniffer operates at the network layer (unlike an HTTP-based traffic monitor at the application layer), the packets are intercepted transparently to the client. This means that the packet sniffer is a passive service, which is typically used for management and monitoring instead of general policy enforcement. For more details, see Packet sniffers on page 301.
HTTP services groups
An HTTP services group is a container around one or more HTTP services. Usually, an HTTP services group is configured for a particular type of HTTP service. For example, you could have an HTTP
Interfaces group that contains the configured HTTP interfaces, and another Static Providers group to manage static content providers. While organizing HTTP services by type eases the task of managing services, the API Gateway is flexible enough to enable administrators to organize services into groups according to whatever scheme best suits their requirements. Axway API Gateway 7.5.2
Policy Developer Guide 290
8 API Gateway instances
This section describes a scenario where HTTP services groups can prove useful. It first describes an HTTP service group that handles HTTP traffic, and then shows how you can use a second SSL service group to process SSL traffic on a separate channel. HTTP interfaces and relative paths
HTTP services groups should consist of at least one HTTP interface together with at least one relative path. The HTTP interface determines which TCP port the API Gateway instance listens on, while you can use the relative path to map a request received on a particular path (request URI) to specific policies. You can add several HTTP interfaces to the groups, in which case requests received on any one of the opened ports are processed in the same manner. For example, http://
[HOST]:8080/test and http://[HOST]:8081/test requests can both be processed by the same policy (mapped to the /test relative path). Similarly, you can add multiple relative paths to this HTTP services group, where each path is bound to a specific policy or chain of policies. For example, if a request is made to http://
[HOST]:8080/a, it is processed by Policy A; whereas if a request is made to http://
[HOST]:8080/b, it is handled by Policy B. As a side-effect of this configuration, requests made to the other interface are also processed by the same policy, meaning that a request made to http://[HOST]:8081/b is also handled by Policy B. Effectively, this means that relative paths configured under the HTTP services group are bound to all HTTP interfaces configured for that group. If you have two interfaces listening on ports 8080 and 8081, requests to http://[HOST]:8080/a and http://[HOST]:8081/a are handled identically by the API Gateway instance.
Example HTTP service group
What happens if you want to distinguish between receiving requests on the two different ports? For example, you want requests to http://[HOST]:443/a to be processed by an SSL Validation
policy, while requests for http://[HOST]:8080/a to be handled by a standard Schema
Validation policy. The addition of a new HTTP services group can resolve this issue. The new SSL HTTP
Services Group opens a single HTTPS interface that listens on port 443, and is configured with a relative path of /a to handle requests on this path. The configuration is summarized in the following table:
Services Group
HTTP Port
Relative Path
Policy
HTTP Services Group
8080
/a
Schema Validation Policy
SSL HTTP Services Group
443
/a
SSL Validation Policy
Axway API Gateway 7.5.2
Policy Developer Guide 291
8 API Gateway instances
With this configuration, when you receive a request on http://[HOST]:8080/a, it is handled by the Schema Validation Policy. But when you get a request to the SSL port on http://
[HOST]:443/a it is processed by the SSL Validation Policy. Using HTTP services groups in this way, you can configure the API Gateway instance to dispatch requests received on the same path (for example, /a) to different policies depending on the port on which the request was accepted.
Default HTTP service groups
By default, the API Gateway ships with preconfigured HTTP services groups (for example, Default Services and Management Services). By default, Management
Services are not displayed in the Policy Studio, but can be displayed using the Preferences menu. The Default Services group contains some general purpose default policies for use with an out-of-the-box installation of the API Gateway. In addition to the preconfigured service groups, you can add new HTTP services groups to dispatch requests to different policies, based on the port on which the requests are received. For more details on the default Management Services group, see Management services on page 299.
Add an HTTP service group
To add a service group, perform the following steps:
1. Right-click the API Gateway instance, and select Add HTTP Services. 2. Enter a name for the group in the HTTP Services dialog. 3. To enable Cross Origin Resource Sharing (CORS) for this HTTP service, select CORS tab, and click the button on the right to select a preconfigured CORS profile. By default, no profile is selected, which means that CORS is disabled. For details on CORS, see Cross-Origin Resource Sharing on page 268.
4. In the Select CORS Profile dialog, if no profiles have already been configured, right-click CORS Profiles, and select Add a CORS Profile. You can also right-click an existing profile, and select Edit to update its settings. For details on CORS settings, see Add a CORS profile on page 269.
When an HTTP service group is created, you can configure it with the HTTP services described in this topic.
HTTP and HTTPS interfaces
An HTTP interface defines the address and port that the API Gateway instance listens on. There are two types of interface: HTTP and HTTPS. The HTTP interface handles standard non-authenticated HTTP requests, while the HTTPS interface can accept mutually authenticated SSL connections.
Axway API Gateway 7.5.2
Policy Developer Guide 292
8 API Gateway instances
To create an HTTP interface, select the HTTP Service group in the Policy Studio tree (for example, Environment Configuration > Listeners > API Gateway > Default Services). Right-click the Ports node, and select Add HTTP or Add HTTPS.
Configure Network settings
The following fields on the Network tab are common to both the HTTP Interface and HTTPS
Interface dialogs, and must be configured for both types of interface:
Port:
The port number that the API Gateway instance listens on for incoming HTTP requests.
Address:
The IP address or host of the network interface on which the API Gateway instance listens. For example, you can configure the instance to listen on port 80 on the external IP address of a machine, while having a web server running on the same port but on the internal IP address of the same machine. By entering *, the instance listens on all interfaces available on the machine hosting the API Gateway.
Protocol:
Select the Internet Protocol version that this Interface uses. You can select IPv4, IPv6, or both of these protocol versions. Defaults to IPv4.
Trace level:
The level of trace output. The possible values in order of least verbose to most verbose output are:
l FATAL
l ERROR
l INFO
l DEBUG
l DATA
The default trace level is read from the system settings.
Enable interface:
Deselect this setting to disable this HTTP interface. This setting is enabled by default.
Configure Traffic Monitor settings
The fields on the Traffic Monitor tab are common to the HTTP Interface and HTTPS Interface dialogs. To override the system-level settings at HTTP or HTTPS interface level, select Override
settings for this port, and configure the relevant options. For more details, see the API Gateway Administrator Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 293
8 API Gateway instances
Configure Advanced settings
The following fields on the Advanced tab are common to both the HTTP Interface and HTTPS
Interface dialogs, and must be configured for both types of interface:
Backlog:
When the API Gateway instance is busy handling concurrent requests, the operating system can accept additional incoming connections. In such cases, a backlog of connections can build up while the operating system waits for the instance to finish handling current requests.
The specified Backlog value is the maximum number of connections the API Gateway instance allows the operating system to accept and queue up until the instance is ready to read them. The larger the backlog, the larger the memory usage. The smaller the backlog, the greater the potential for dropped connections.
Idle Timeout:
The API Gateway supports the use of HTTP 1.1 persistent connections. The Idle Timeout is the time that the API Gateway instance waits after sending a response over a persistent connection before it closes the connection. Defaults to 60000 milliseconds (60 seconds).
Typically, a client tells the instance that it wants to use a persistent connection. The instance acknowledges this instruction and decides to keep the connection open for a certain amount of time after sending the response to the client. If the client does not reuse the connection by sending up another request within the Idle Timeout period, the instance closes the connection.
Active Timeout:
When the API Gateway instance receives a large HTTP request, it reads the request off the network as it becomes available. If the time between reading successive blocks of data exceeds the Active
Timeout, the instance closes the connection. Defaults to 60000 milliseconds (60 seconds).
This guards against a client closing the connection while in the middle of sending data. Imagine the client's network connection is pulled out of the machine while in the middle of sending data to the instance. When the instance has read all the available data off the network, it waits the Active
Timeout period of time before closing the connection.
Maximum Memory per Request:
The maximum amount of memory in bytes that the API Gateway instance allocates to each request. For more details, see the API Gateway Administrator Guide.
Input Encodings:
Click the browse button to specify the HTTP content encodings that the API Gateway can accept from peers. The available content encodings include gzip and deflate. By default, the content encodings configured in the Default Settings are used. You can override this setting at the HTTP interface level and in the Remote Host Settings. For more details, see Compressed content encoding on page 863.
Output Encodings:
Click the browse button to specify the HTTP content encodings that the API Gateway can apply to outgoing messages. The available content encodings include gzip and deflate. By default, the content encodings configured in the Default Settings are used. You can override this setting at the HTTP interface level and in the Remote Host Settings. For more details, see Compressed content encoding on page 863.
Axway API Gateway 7.5.2
Policy Developer Guide 294
8 API Gateway instances
Transparent Proxy - allow bind to foreign address:
Enables the use of the API Gateway as a transparent proxy o n Linux systems with the TPROXY kernel option set. When selected, the value in the Address field can specify any IP address, and incoming traffic for the configured address/port combinations is handled by the API Gateway. For more details and an example, see Configure a transparent proxy on page 305. Include correlation ID in headers:
Specifies whether to insert the correlation ID in outbound messages. For the HTTP transport, this means that an X-CorrelationID header is added to the outbound message. This is a transaction ID that is tagged to each message transaction that passes through the API Gateway, and which is used for traffic monitoring in the API Gateway Manager web console. You can use the correlation ID to search for messages in the console. You can also access the its value using the id message attribute in an API Gateway policy. An example correlation ID value is Id-54bbc74f515d52d71a4c0000 . This setting is selected by default.
Threat Protection Settings:
Click the browse button, and select a Threat Protection Profile to protect this interface with Apache ModSecurity threat protection rules. ModSecurity is a toolkit for real-time HTTP traffic monitoring, logging, and access control, which helps to mitigate application-level threats to APIs. The ModSecurity engine is embedded in API Gateway to provide API firewalling. If no threat protection profiles have been configured, right-click the Threat Protection Profiles node in the dialog, and select Add a Threat Protection Profile. Configure the following settings:
l Name: Enter a required profile name to display in Policy Studio.
l Configuration directory: Enter the name of the directory that stores the threat protection configuration file. Defaults to ${environment.VDISTDIR}/system/conf/threat-
protection/default. l Configuration file: Enter the threat protection configuration file name. Defaults to modsecurity.conf. l Rules directory: Enter the name of the subdirectory that stores the threat protection rules. Defaults to activated_rules. l Alert policy: Select an optional API Gateway policy to execute when a threat protection rule is triggered.
No threat protection profile is selected by default. When a profile is selected, all traffic is processed by the ModSecurity engine, and threats are rejected based on the configured rules. For more details on API firewalling, see the API Gateway Administrator Guide. Configure Conditions for an HTTP Interface
You can configure the API Gateway to bring down an active HTTP interface if certain conditions fail to hold. For example, the HTTP interface can be brought down if a remote host is not available or if a physical network interface on the machine on which the API Gateway is running loses connectivity to the network. For more details, see Configure conditions for HTTP interfaces on page 303. Axway API Gateway 7.5.2
Policy Developer Guide 295
8 API Gateway instances
HTTPS interfaces only
This section describes settings that apply to HTTPS interfaces only.
Configure Network settings
You must complete the same fields for an HTTPS interface on the Network tab as for an HTTP interface, with the addition of the following setting:
X.509 Certificate:
Click the X.509 Certificate button to select the certificate that the API Gateway uses to authenticate itself to clients during the SSL handshake. The list of certificates currently stored in the Certificate Store is displayed. Select a single certificate from this list.
Configure Mutual Authentication settings
You can configure clients to authenticate to the API Gateway on the Mutual Authentication tab. The following options are available:
l Ignore Client Certificates
The API Gateway ignores client certificates if they are presented during the SSL handshake.
l Accept Client Certificates
Client certificates are accepted when presented to the API Gateway, but clients that do not present certificates are not rejected.
l Require Client Certificates
The API Gateway only accepts connections from clients that present a certificate during the SSL handshake.
Client certificates are typically issued by a Certificate Authority (CA). In most cases, the CA includes a copy of its certificate in the client certificate so that consumers of the certificate can decide whether or not to trust the client based on the issuer of the certificate. A chain of CAs can also issue the client certificate. For example, a top-level organization-wide CA (for example, Company CA) may have issued department-wide CAs (for example, Sales CA, QA CA, and so on), and each department CA is then responsible for issuing all department members with a client certificate. In such cases, the client certificate may contain a chain of one or more CA certificates. Maximum depth of client certificate chain:
You can use this field to configure how many CA certificates in a chain of one or more are trusted when validating the client certificate. By default, only one issuing CA certificate is used, and this certificate must be checked in the list of trusted root certificates. If more than one certificate is used, only the top-level CA must be considered trusted, while the intermediate CA certificates are not.
Root Certificate Authorities trusted for mutual authentication:
Select the root CA certificates that the API Gateway considers trusted when authenticating clients during the SSL handshake. Only certificates signed by the CAs selected here are accepted.
Axway API Gateway 7.5.2
Policy Developer Guide 296
8 API Gateway instances
Configure Advanced SSL settings
You can complete the following settings on the Advanced (SSL) tab:
Check that the SSL certificate's Subject CN resolves to network address:
When this setting is selected the API Gateway attempts to resolve the SSL certificate's Subject Common Name (CN) to the network address configuring the SSL interface. If the Subject CN cannot be resolved to the network address, a warning is output in the error traces. This setting is selected by default. You can deselect this setting to disable checking the certificate's Subject CN. SSL Server Name Identifier (SNI):
You can specify the host names requested by clients in the SSL Server Name Identifier (SNI) table. SNI is an optional TLS feature where the client indicates to the server the host name used to resolve the server address. This enables a server to present different certificates for clients to ensure the correct site is contacted.
For example, the server IP address is 192.168.0.1. The DNS is consulted by clients to resolve a host name to an address, and the server address is contacted using TCP/IP. If both www.acme.com and www.anvils.com resolve to 192.168.0.1, without SNI, the server does not know which host name the client uses to resolve the address, because it is not party to the client DNS name resolution. The server may certify itself as either service, but when the connection is established, it does not know which host name the client connects to.
With SNI, the client provides the name of the host (for example, www.anvils.com) in the initial SSL exchange, before the server presents its certificate in its distinguished name(for example, CN=www.anvils.com). This enables the server to certify itself correctly as providing a service for the client's requested host name. To specify an SNI, perform the following steps:
1. Click the Add button to configure a server host name in the SSL Server Name Identifier
(SNI) dialog. 2. Specify the server host name in the Client requests server name field.
3. Click Server assumes identity to import a Certificate Authority certificate into the Certificate Store.
4. Click OK.
Ciphers:
You can specify the ciphers that the server supports in the Ciphers field. The server selects the highest strength cipher (that is also supported by the client) from this list as part of the SSL handshake. For more information on the syntax of this setting, see the OpenSSL documentation.
Note
The default cipher string of FIPS:!SSLv3:!aNULL performs the following:
l Enables FIPS-compatible cipher suites only
l Explicitly blocks cipher suites that require SSLv3 or lower
l Forces the use of TLSv1.2 only
l Forbids unauthenticated cipher suites
Axway API Gateway 7.5.2
Policy Developer Guide 297
8 API Gateway instances
SSL session cache size:
Specifies the number of idle SSL sessions that can be kept in memory. Defaults to 32. If there are more than 32 simultaneous SSL sessions, this does not prevent another SSL connection from being established, but means that no more SSL sessions are cached. A cache size of 0 means no cache, and no outbound SSL connections are cached.
Tip
You can use this setting to improve performance because it caches the slowest part of establishing the SSL connection. A new connection does not need to go through full authentication if it finds its target in the cache.
At DEBUG level or higher, the API Gateway outputs trace when an entry goes into the cache, for example:
DEBUG
09:09:12:953 [0d50] cache SSL session 11AA3894 to support.acme.com:443
If the cache is full, the output is as follows:
DEBUG
09:09:12:953 [0d50] enough cached SSL sessions 11AA3894 to
support.acme.com:443 already
Ephemeral DH key parameters:
This setting specifies the parameters used to generate Diffie Hellman (DH) keys. The DH key agreement algorithm is used to negotiate a shared secret between two SSL peers. This enables two parties without prior knowledge of each other to jointly establish a shared secret key over an insecure communication channel.
When DH key parameters are not specified, the SSL client uses the public RSA key in the server's certificate to encrypt data sent to the SSL server and establish a shared secret with the server. However, if the RSA key is ever discovered, any previously recorded encrypted conversations can be decrypted. DH key agreement offers Perfect Forward Secrecy (PFS) because there is no such key to be compromised.
There are two options when setting DH key parameters:
l Enter a number (for example, 512 ), and the server automatically generates DH parameters with a prime number of the correct size.
l Paste the Base64 encoding of an existing serialized DH parameters file. You can use standard DH parameters based on known good prime numbers. OpenSSL ships with the dh512.pem and dh1024.pem files. For example, you can set the DH parameters to the following Base64encoded string in pdh512.pem:
-----BEGIN DH PARAMETERS----MEYCQQD1Kv884bEpQBgRjXyEpwpy1obEAxnIByl6ypUM2Zafq9AKUJsCRtMIPWakXUGfnHy9iUsiGSa6q6Je
w1X
pKgVfAgEC
-----END DH PARAMETERS-----
Axway API Gateway 7.5.2
Policy Developer Guide 298
8 API Gateway instances
The DH parameters setting is required if the server is using a DSA-keyed certificate, but also has an effect when using RSA-based certificates. DH (or similar) key agreement is required for DSA-based certificates because DSA keys cannot be trivially used to encrypt data like RSA keys can.
Note
The EDH key is always used once only to guarantee forward secrecy. This ensures that if the key is compromised, previous keys will not be compromised.
SSL Protocol Options:
You can configure the following SSL protocol options:
Option
Description
Do not use
the SSL v2
protocol
Specifies not to use SSL v2 for incoming connections to avoid any weaknesses in this protocol. This is selected by default.
Do not use
the SSL v3
protocol
Specifies not to use SSL v3 for incoming connections to avoid any weaknesses in this protocol. This is selected by default.
Do not use
the TLS v1
protocol
Specifies not to use TLS v1.0 for incoming connections to avoid any weaknesses in this protocol. This is selected by default.
Do not use
the TLS
Specifies not to use TLS v1.1 for incoming connections to avoid any weaknesses in this protocol. This is selected by default.
v1.1
protocol
Do not use
the TLS
v1.2
protocol
Specifies not to use TLS v1.2 to avoid any weaknesses in this protocol. This is not selected by default.
Prefer local
cipher
preferences
over
client's
proposal
When choosing a cipher during the SSL/TLS handshake, the client's preferences are selected by default from the list of ciphers supported by the client and the server. When this option is selected, the server's preferences are used instead. This option is not selected by default. For more details on ciphers, see the OpenSSL documentation.
Management services
The Management Services group exposes a number of services used by the Admin Node Manager and API Gateway Analytics for remote configuration and monitoring. The Management Services server process, interfaces, and policies are displayed in the Policy Studio tree. The Management
Axway API Gateway 7.5.2
Policy Developer Guide 299
8 API Gateway instances
Services policy container is displayed in the tree under the Policies node. The Management
Services HTTP interfaces are displayed under the Environment Configuration > Listeners node.
By default, the Management Services group consists of the following:
HTTP Interface:
By default, the Admin Node Manager exposes all its management services on port 8090 so that they can be configured remotely. At startup, the Policy Studio can connect to this port to read and write API Gateway configuration data. By default, the API Gateway Analytics exposes all its management services on port 8040. For more details, see Change the management services port on page 301. Relative Path: /
The / relative path is mapped to a default management policy called Protect Management
Interface, which is available under the Management Services policy container. This policy performs HTTP Basic authentication and passes control to the Call Internal Service filter. This dispatches a message to a Servlet Application or Static Content Provider based on the path on which the request was received.
For example, with the default configuration, assume that a request is received on http://localhost:8090/configuration. The following steps summarize the request processing cycle:
1. When a relative path of / is configured, it matches all incoming requests, and requests are dispatched to whatever policy the relative path is mapped to. In this case, the relative path is mapped to the Protect Management Interface policy, and so the request is passed to this policy.
2. The Protect Management Interface policy performs HTTP basic authentication on the originator of the request. Authentication is necessary because all configuration operations are considered privileged operations and should only be carried out by those with the authority to do so. If the originator can be successfully authenticated, the Call Internal Service filter is invoked.
3. The Call Internal Service filter is a special filter that passes messages to a Servlet Application or Static Content Provider. In this case, because the message is received on the management interface (port 8090), the filter attempts to match the relative path on which the request was received against all the Servlets and Content Providers configured in the same Services Group
as this interface.
4. The configured Servlets and Content Providers for the Management Services group include /configuration/ and /api/. Because the request is received on the /configuration/ path, this matches the /configuration/ Servlet Application, which is invoked.
Servlet Application: /configuration/
The Policy Studio running on a different host to the API Gateway can connect to this URL to remotely configure the API Gateway. For example if the API Gateway is running on a host called SERVER, the Policy Studio can connect to http://SERVER:8090/configuration/ on startup so that it can remotely configure policies running at the API Gateway on the SERVER host.
Axway API Gateway 7.5.2
Policy Developer Guide 300
8 API Gateway instances
Note
Changing the interfaces, relative path, servlet applications, or static content provider exposed under the Management Services group can prevent the Admin Node Manager from functioning correctly. Because of this, the Management Services group is hidden by default, and should only be modified under strict supervision from the Axway Support team.
Change the management services port
The default management services port used by the Admin Node Manager is 8090. To specify a different port, perform the following steps:
1. Under the Environment Configuration > Listeners node in the Policy Studio tree, rightclick the Management Services HTTP interface, and select Edit.
2. Specify an updated value in the Port field (for example, 8091), and click OK.
3. Click the Deploy button in the Policy Studio toolbar, or press F6 to deploy the update.
4. Restart Policy Studio. You must restart Policy Studio when Management Services are updated.
5. Use the updated port number in the URL to reconnect Policy Studio (for example, https://HOST:8091/api).
Note
Management Services apply to the Admin Node Manager and API Gateway Analytics only. You should only modify Management Services under strict advice and supervision from the Axway Support team. Packet sniffers
Overview
Packet Sniffers are a type of Passive Service. Rather than opening up a TCP port and actively listening for requests, the Packet Sniffer passively reads raw data packets off the network interface. The Sniffer assembles these packets into complete messages that can then be passed into an associated policy.
Because the Packet Sniffer operates passively (does not listen on a TCP port) and, therefore, completely transparently to the client, it is most useful for monitoring and managing web services. For example, the Sniffer can be deployed on a machine running a web server acting as a container for web services. Assuming that the web server is listening on TCP port 80 for traffic, the Packet Sniffer can be configured to read all packets destined for port 80 (or any other port, if necessary). The packets can then be marshalled into complete HTTP/SOAP messages by the Sniffer and passed into a policy that logs the message to a database, for example. Note
On UNIX/Linux platforms, the API Gateway must be started by the root user to gain access to the raw packets. Axway API Gateway 7.5.2
Policy Developer Guide 301
8 API Gateway instances
Configuration
Since Packet Sniffers are mainly for use as passive monitoring agents, they are usually created within their own HTTP Service Group. For example, you can create a new Service Group for this purpose by right-clicking on the API Gateway instance, selecting the Add HTTP Services menu option, and entering Packet Sniffer Group on the HTTP Services dialog. You can then add a relative path service to this Group by right-clicking the Packet Sniffer Group, and selecting the Add Relative Path menu option. Enter a path in the field provided, and select the policy that you want to dispatch messages to when the Packet Sniffer detects a request for this path (after it assembles the packets). For example, if the relative path is configured as /a, and the Packet Sniffer assembles packets into a request for this path, the request is dispatched to the policy selected in the relative path service. Finally, you can add the Packet Sniffer by right-clicking the Packet Sniffer Group node, selecting Packet Sniffer, and then the Add menu option. Complete the following fields on the Packet
Sniffer dialog:
Device to Monitor:
Enter the name or identifier of the network interface that the Packet Sniffer is to monitor. The default entry is any. Note
This setting is only valid on UNIX. On UNIX-based systems, network interfaces are usually identified using names like eth0, eth1, and so on. On Windows, these names are more complicated (for example, \Device\NPF_{00B756E0-518A-4144 ... }.
Filter:
The Packet Sniffer can be configured to only intercept certain types of packets. For example, it can ignore all UDP packets, only intercept packets destined for port 80 on the network interface, ignore packets from a certain IP address, listen for all packets on the network, and so on. The Packet Sniffer uses the libpcap library filter language to achieve this. This language has a complicated but powerful syntax that allows you to filter what packets are intercepted and what packets are ignored. As a general rule, the syntax consists of one or more expressions combined with conjunctions, such as and, or, and not. The following table lists a few examples of common filters and explains what they filter:
Filter expresssion
Description
port 80
Capture only traffic for the HTTP Port ( 80).
host 192.168.0.1
Capture traffic to and from IP address 192.168.0.1.
tcp
Axway API Gateway 7.5.2
Capture only TCP traffic.
Policy Developer Guide 302
8 API Gateway instances
Filter expresssion
Description
host 192.168.0.1 and port
Capture traffic to and from port 80 on IP address 80
192.168.0.1.
tcp portrange 8080-8090
Capture all TCP traffic destined for ports from 8080 through to 8090.
tcp port 8080 and not src
Capture all TCP traffic destined for port 8080 but not host 192.168.0.1
from IP address 192.168.0.1.
The default filter of tcp captures all TCP packets arriving on the network interface. For more information on how to configure filter expressions like these, refer to the tcpdump man page available from http://www.tcpdump.org/tcpdump_man.html.
Promiscuous Mode:
When listening in promiscuous mode, the Packet Sniffer captures all packets on the same Ethernet network, regardless of whether or not the packets are addressed to the network interface that the Sniffer is monitoring. Configure conditions for HTTP interfaces
Overview
In certain cases, it may be desirable to pull down the HTTP interface that accepts traffic for the API Gateway. For example, if the back-end web service is unavailable or if the physical interface on the machine loses connectivity to the network, it is possible to shut down the HTTP interface so that it stops accepting requests. A typical scenario where this functionality proves useful is as follows:
l A load balancer sits in front of several running instances of the API Gateway and round-robins requests between them all. l A client sends SSL requests through the load balancer, which forwards them opaquely to one of the API Gateway instances. l The API Gateway terminates the SSL connection, processes the message with the configured policy, and forwards the request onto the back-end web service. In this deployment scenario, the load balancer does not want to keep sending requests to an instance of the API Gateway if it has either lost connectivity to the network or if the back-end web service is unavailable. If either of these conditions hold, the load balancer should stop attempting to route requests through this instance of the API Gateway and use the other instances instead.
Axway API Gateway 7.5.2
Policy Developer Guide 303
8 API Gateway instances
So then, how can the load balancer determine the availability of the web service and also the connectivity of the machine hosting the API Gateway to the network on which the web service resides? Given that the request from the client to the API Gateway is over SSL, the load balancer has no way of decrypting the encrypted SSL data to determine whether or not a SOAP Fault, for example, has been returned from the API Gateway to indicate a connection failure. The solution is to configure certain conditions for each HTTP interface, which must hold for the HTTP interface to remain available and accept requests. If any of the associated conditions fail, the interface is brought down and does not accept any more requests until the failed condition becomes true and the HTTP interface is restarted. When the load balancer receives a connection failure from the API Gateway (which it does when the HTTP interface is down) it stops sending requests to this API Gateway and chooses to round-robin requests amongst the other instances instead.
The following conditions can be configured on the HTTP interface:
l Requires Endpoint:
The HTTP interface remains up only if the remote host is available. The remote host is polled periodically to determine availability so that the HTTP interface can be brought back up automatically when the Remote Host becomes available again.
l Requires Link:
The HTTP interface remains up only if a named physical interface has connectivity to the network. As soon as a down physical interface regains connectivity, the HTTP interface automatically comes back up again.
You can configure conditions for an HTTP interface using the HTTP interface Ports node (for example, *:8080) under the API Gateway instance in the Policy Studio tree. For example, this is available under Environment Configuration > Listeners > API Gateway. Right click the HTTP interface in the right pane, and select Add Condition menu option, and then either the Requires Endpoint or Requires Link option depending on your requirements. The sections below describe how to configure these conditions.
Configure Requires Endpoint condition
A Requires Endpoint condition can be configured in cases where you only want to keep the HTTP interface up if the back-end web service (the Remote Host) is available. An HTTP Watchdog can be configured for the Remote Host, which is then responsible for polling the Remote Host periodically to ensure that the web service is available. See Configure remote host settings on page 283 and Configure HTTP watchdog on page 288 for more information.
Remote Host:
The HTTP interface shuts down if the Remote Host selected here is deemed to be unavailable. The Remote Host can be continuously polled so that the interface can be brought up again when the Remote Host becomes available again. Axway API Gateway 7.5.2
Policy Developer Guide 304
8 API Gateway instances
Configure Requires Link condition
The Requires Link condition is used to bring down the HTTP interface if a named physical network interface is no longer connected to the network. For example, if the cable is removed from the Ethernet switch, the dependent HTTP interface is brought down immediately. The HTTP interface only starts listening again when the physical interface is connected to the network again (when the Ethernet cable is plugged back in).
Note
The Requires Link condition is only available on UNIX/Linux platforms.
Interface Name:
The HTTP interface is brought down if the physical network interface named here is no longer connected to the network. On UNIX platforms, physical network interfaces are usually named eth0, eth1, and so on. Configure a transparent proxy
Overview
On Linux systems with the TPROXY kernel option enabled, you can configure the API Gateway as a transparent proxy. This enables the API Gateway to present itself as having the server's IP address from the point of view of the client, or having the client's IP address from the point of view of the server. This can be useful for administrative or network infrastructure purposes (for example, to keep using existing client/server IP addresses, and for load-balancing). You can configure transparent proxy mode both for inbound and outbound API Gateway connections:
l Incoming interfaces can listen on IP addresses that are not assigned to any interface on the local host.
l Outbound calls can present the originating client's IP address to the destination server.
Both of these options act independently of each other.
Configure transparent proxy mode for incoming
interfaces
To enable transparent proxy mode on an incoming interface, perform the following steps:
1. In the Policy Studio tree, expand the Environment Configuration > Listeners > API
Gateway node.
2. Right-click your service, and select Add Interface > HTTP or HTTPS to display the appropriate dialog (for example, Configure HTTP Interface).
Axway API Gateway 7.5.2
Policy Developer Guide 305
8 API Gateway instances
3. Select the check box labeled Transparent Proxy (allow bind to foreign address). When selected, the value in the Address field can specify any IP address, and incoming traffic for the configured address/port combinations is handled by the API Gateway.
For more details on configuring interfaces, see Configure HTTP services on page 290.
Configure transparent proxy mode for outgoing
calls
Transparent proxy mode for outgoing calls must be enabled at the level of a connection filter in a policy. To enable transparent proxy mode for outbound calls, perform the following steps:
1. Ensure that your policy contains a connection filter (for example, Connect to URL or Connection, available from the Routing category in the filter palette).
2. In your connection filter, select the Settings tab and expand the Proxy section.
3. Select the check box labeled Transparent Proxy (present client's IP address to server). When selected, the IP address of the original client connection that caused the policy to be invoked is used as the local address of the TCP connection to the destination server.
For more details on configuring connection filters, see Connection on page 786 and Connect to URL on page 780.
Transparent proxy example
A typical configuration example of transparent proxy mode is shown as follows:
In this example, the remote client’s address is 172.16.0.99, and it is attempting to connect to the server at 10.0.0.99 on port 80. The front-facing firewall is configured to route traffic for 10.0.0.99 through the API Gateway at address 192.168.0.9. The server is configured to use the API Gateway at address 10.0.0.1 as its default IP router.
The API Gateway is multihomed, and sits on both the 192.168.0.0/24 and 10.0.0.0/24 networks. In the Configure HTTP Interface dialog, the API Gateway is configured with a listening address of 10.0.0.99 and port of 80 on the Network tab, and with transparent proxy mode enabled on the Advanced tab. For example:
Axway API Gateway 7.5.2
Policy Developer Guide 306
8 API Gateway instances
The API Gateway accepts the incoming call from the client, and processes it locally. However, there is no communication with the server yet. The API Gateway can process the call to completion and respond to the client—it is masquerading as the server.
If the API Gateway invokes a connection filter when processing this call (with transparent proxying enabled), the connection filter consults the originating address of the client, and binds the local address of the new outbound connection to that address before connecting. The server then sees the incoming call on the API Gateway originating from the client ( 172.16.0.99), rather than either of the API Gateway's IP addresses. The following dialog shows the example configuration for the Connect to URL filter:
Axway API Gateway 7.5.2
Policy Developer Guide 307
8 API Gateway instances
The result is a transparent proxy, where the client sees itself as connecting directly to the server, and the server sees an incoming call directly from the client. The API Gateway processes two separate TCP connections, one to the client, one to the server, with both masquerading as the other on each connection.
Note
Either side of the transparent proxy is optional. By configuring the appropriate settings for the incoming interface or the connection filter, you can masquerade only to the server, or only to the client. Configure relative paths
Overview
A relative path b inds policies to a specific relative path location (for example /test/path). When the API Gateway receives a request on the specified path, it invokes the specified policy or policy chain. This topic explains configuring relative path resolvers. For details on configuring policies, see Manage policies on page 74. You can use a Static Content Provider or Static File Provider to serve static HTTP content or files from a directory. In this case, the API Gateway instance acts as a web server. The API Gateway instance can also act as a Servlet Application c ontainer, which enables you to drop servlets into the HTTP Services configuration. This should only be used by developers with specific requirements under strict advice from Axway Support. Relative paths can have nested child resolvers of the following type:
l Relative path
l Static content provider
l Static file provider
l Servlet application
This topic explains how to use the Policy Studio to configure each of these relative path resolver types. For details on configuring HTTP Services Groups and HTTP Interfaces, see Configure HTTP services on page 290.
Configure a relative path
To configure a relative path for a specific HTTP Service Group (for example, Default Services), perform the following steps:
1. In the Policy Studio tree, select Environment Configuration > Listeners > API Gateway > Default Services > Paths.
2. Right-click Paths, and select Add > Relative Path. You can also click Add on the right.
Axway API Gateway 7.5.2
Policy Developer Guide 308
8 API Gateway instances
3. In the Configure Relative Path dialog, specify whether to enable listening on the specified path using the Enable this path resolver setting, which is set by default.
Alternatively, when editing a policy, you can click Add Relative Path at the bottom of the policy canvas beside the Context drop-down list. The next sections explain how to configure the settings on the Configure Relative Path dialog.
Policies settings
Use the Policies tab to specify the relative path and the policies that are called. The API Gateway invokes the selected policies when it receives a request on the specified path. You can specify a single policy or a chain of policies. Policies are called in the order displayed on this tab. Complete the following fields:
When a request arrives that matches the path:
Enter a relative path (for example, /test/path) for the selected HTTP Services Group. Requests received on this relative path are processed by the policies selected on this tab.
Global Request Policy:
If a global request policy is configured, when you select this setting, the global request policy is called first in the policy chain. For more details, see Configure global policies on page 76.
Path Specific Policy:
To configure a path-specific policy, select this setting, and browse to select a policy from the dialog. You can search for a specific policy by entering its name in the text box, and the policy tree is filtered automatically. The Path Specific Policy field is auto-populated with the currently selected policy when the dialog is launched using the Add Relative Path button at the bottom of the policy canvas.
Global Response Policy:
If a global response policy is configured, when you select this setting, the global response policy is called last in the policy chain. For more details, see Configure global policies on page 76.
When you select multiple policies to form a policy chain, the behavior is the same as for a policy shortcut chain filter. Policies are only evaluated when selected, and when the policy can be reached. If any reachable policy fails, the chain fails, and no more policies are evaluated.
Logging settings
The Logging Settings tab enables you to configure the logging level for all filters executed on the relative path, and to configure when message payloads are logged.
Logging Level
You can configure the following settings on all filters executed on the specified relative path:
Axway API Gateway 7.5.2
Policy Developer Guide 309
8 API Gateway instances
Logging
Level
Description
Fatal
Logs Fatal log points that occur on all filters executed. Failure
Logs Failure log points that occur on all filters executed. This is the default logging level.
Success
Logs Success log points that occur on all filters executed. For details on logging levels, and configuring logging for a filter, see Set transaction log level and log message on page 758.
Payload Level
You can configure the following settings on the specified relative path:
Payload Logging
Description
On receive request
from client
Log the message payload when a request arrives from the client. On send response to
client
Log the message payload before the response is sent back to the client.
On send request to
remote server
Log the message payload before the request is sent using any Connection or Connect to URL filters deployed in policies.
On receive response
from remote server
Log the message payload when the response is received using any Connection or Connect to URL filters deployed in policies.
For details on how to log message payloads at any point in a specific policy, see Log message payload on page 747.
Access Log
Select the Include in server access log records setting to add this relative path to the API Gateway Access Log. This enables the Access Log at the service level. This setting is not selected by default. Note
You must also enable the Transaction Access Log at the API Gateway level. In the Policy Studio tree, select Environment Configuration > Server Settings > Logging > Access Log, and ensure that Writing to Transaction Access Log is enabled. For more details, see the API Gateway Administrator Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 310
8 API Gateway instances
HTTP method settings
The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which means that all HTTP Methods are accepted. You can override the default behavior, and select an appropriate HTTP method for the relative path from the list.
You can also configure multiple HTTP methods on paths of the same name. This enables you to call different policies for different HTTP methods, as shown in the following example:
In this example, the /test path is configured three times, each using a different HTTP Method as follows: l If a GET request is sent to the API Gateway on the /test path, the Test1 policy is executed.
l If a POST request is sent, the Test2 policy is executed.
l If any other type of request is sent (for example, DELETE, PUT, and so on), the Test3 policy is executed.
For details on the Path/Test1 subpath in this example, see Nested relative paths on page 312.
Advanced settings
On the Advanced tab, select whether to resolve this relative path using an Exact path match. The default is to use a longest path match (explained in the next section). This setting enables you to further restrict the match to an exact path match (for example, test1/helloService). This setting is not selected by default. CORS settings
On the CORS tab, you can configure settings for Cross Origin Resource Sharing (CORS). For details on CORS, see Cross-Origin Resource Sharing on page 268. By default, the CORS profile set at the HTTP service level is used for all child resolvers of the HTTP service. However, you can override this at the relative path level as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 311
8 API Gateway instances
1. In the CORS Usage field, select Override CORS using the following profile. By default, no CORS profile is selected, and the parent settings are used.
Note
Relative paths can act as HTTP Services, and can accommodate child resolvers. This means that when a Relative Path has children, and has a CORS profile configured, by default, the children use the parent profile (unless a child overrides it).
2. In the CORS Profile field, click the button on the right to select a preconfigured CORS Profile. 3. If no CORS Profiles have already been configured, right-click CORS Profiles, and select Add a
CORS Profile. You can also right-click an existing profile, and select Edit to update its settings. For details on CORS settings, see Add a CORS profile on page 269.
Nested relative paths
Using the example shown in HTTP method settings on page 311, when you have a path / that has a child subpath (in this case /test1), the following occurs when a request arrives at the API Gateway:
1. Incoming request with path /test1 is received
2. Request is resolved against / (using the longest path match algorithm)
3. API Gateway checks if there are any children (in this case /test1)
4. API Gateway checks if any children can process the request ( /test1 is a match)
5. Path resolution is successful
When the request is being processed, each policy associated with a matching path is executed. In the above example, both / and /test1 make up the match. This means that the policy associated with / is executed first, and if that passes, the policy associated with /test1 is executed. The parent policy uses the Call Internal Service filter, which enables child resolvers to be invoked. Nested paths are generally used as a protection mechanism. For example, a system might be configured with / as the only root path, with a number of children. / could have a Role-Based Access Control (RBAC) policy associated with it protecting all children. If the RBAC policy succeeds, access is granted, and the child policy is executed. If it fails, access is denied. This mechanism is implemented in the Admin Node Manager. You can view this in Policy Studio by opening the Admin Node Manager configuration.
Note
The difference between / having a child /test1, and just having a root relative path of /test1 is due to path resolution and policy execution. To protect /test1 using RBAC, or run a prerequisite policy prior to running the policy associated with /test1, you should use subpaths. You can also achieve this using a Policy Shortcut filter in the policy associated with /test1 (as a root path). This may be sufficient for a small number of root policies. But when a large number of policies need protection, subpaths are a more elegant solution. Children no longer need a Policy Shortcut filter with the policy associated with the parent path as protector.
Axway API Gateway 7.5.2
Policy Developer Guide 312
8 API Gateway instances
Add a nested relative path
To add a child node to a relative path, right-click the appropriate relative path in the Resolvers window, and select the node type (for example, Add > Relative Path). You can add child nodes of the following type:
l Relative path
l Static content provider
l Servlet application
In the following example, the main relative path is /, which calls the Protect policy. Content is served by the underlying Servlet Application and Static Content resolvers only when the Protect policy succeeds:
Note
The parent policy (in this case, Protect) must use the Call Internal Service filter. This acts as a loopback and enables child resolvers to be invoked. When this prerequisite is met, you can add nested relative paths as required.
How to access message attributes from parent
resolvers
Because invoking the Call Internal Service policy results in a new transaction being created (in a loopback connection), a new message whiteboard is generated. This means that you cannot access the message attributes from the parent resolver policy directly. However, in the API Gateway trace, the dwe.protocol.loopback.message message attribute is traced in the child policy. For example:
dwe.protocol.loopback.message {
Value:[email protected]
Type:com.vordel.dwe.http.HTTPMessage
}
Axway API Gateway 7.5.2
Policy Developer Guide 313
8 API Gateway instances
This is the message object from the parent policy. For example, given a parent resolver policy that generates an attr1 message attribute, you can use the following selector in the child resolver policy to access attr1:
${dwe.protocol.loopback.message.attr1}
Order of resolution
The order of resolution for nested relative paths is to first resolve at the parent level. If resolution is successful, and there are children present, then attempt to resolve at the child level. There is no precedence between resolver node types (relative path, static content provider, and servlet application). Path resolution is performed using the longest path match algorithm by default, regardless of whether nested subpaths are used. For details on exact path match, see Advanced settings on page 311.
Example nested path resolution
Using the example relative path shown in Add a nested relative path on page 313, consider the following inbound requests to the Node Manager:
https://testpc:8090/api/deployment/domain/deployments
https://testpc:8090/common/themes/blue/images/server_icon.png
The /api/deployment/domain/deployments request is resolved as follows:
l Matches the root relative path / as a longest path match
l Matches Servlet Application / as a longest path match (1 char)
l Matches Servlet /api as a longest path match (4 char)
l Matches Static Content / as a longest path match (1 char)
l Does not match Servlet Application /configuration
l Does not match Static Content /docs
l Does not match Static Content /kps
In this example, there are two matches, the api Servlet under the Servlet Application on /, and the Static Content on /. Because the API Gateway uses the longest path match, the api Servlet wins, and the request is routed to that resolver. There is no precedence between resolvers, all resolvers are queried for a match.
The /common/themes/blue/images/server_icon.png request is resolved as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 314
8 API Gateway instances
l Matches the root relative path / as a longest path match
l Matches servlet application / as a longest path match (1 char)
l Does not match servlet /api
l Matches static content / as a longest path match (1 char)
l Does not match servlet application /configuration
l Does not match static content /docs
l Does not match static content /kps
In this example, there is only one match, the Static Content on /. In this case, the Servlet Application on / is not considered because none of its children can resolve the request path.
Note
If there are two resolver matches, and each matches on the same path length, the last resolver visited during path resolution is used, in the order in which the resolver was read and loaded from the configuration.
Static content providers
A Static Content Provider can be used with an HTTP Interface to serve static content from a specified directory. A relative path is associated with each Static Content Provider so that requests received on this path are dispatched directly to the provider and are not mapped to a policy in the usual way. For example, you can configure a Static Content Provider to serve content from the c:\docs folder on Windows when it receives requests on the relative path /docs. Add a static content provider
To add a Static Content Provider to an HTTP Services group (for example, Default Services):
1. Select Environment Configuration > Listeners > API Gateway > Default Services >
Paths.
2. Right-click Paths, and select Add > Static Content Provider.
3. Complete the following fields on the General tab.
Relative Path:
Enter the path that you want to receive requests for static content on.
Content Directory:
Enter or browse to the location of the directory that you want to serve static content from.
Index File:
Enter the name of the file to use as the index file for content retrieved from the directory specified in the field above. This file is retrieved by default if no resource is explicitly specified in the request URI. For example, if the client requests http://[HOST]:8080/docs (with only a relative path specified instead of a specific resource), the file specified here is retrieved. This file must exist in the directory specified in the previous field.
Axway API Gateway 7.5.2
Policy Developer Guide 315
8 API Gateway instances
Allow Directory Listings:
If this is selected, the Static Content Provider returns full directory listings for requests specifying a relative path only. For example, if selected, and if a request is received for http://
[HOST]:8080/docs/samples, the list of directories under this directory is returned, assuming that this directory exists on the file system. You can deselect to prevent attacks where a hacker can send up different request URIs in the hope that the server returns some information about the directory structure of the server. HTTP Method:
The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which accepts all HTTP methods. You can override the default behavior, and select an appropriate HTTP method for this resolver from the list. For more details, see HTTP method settings on page 311.
Static file providers
A Static File Provider can be used with an HTTP Interface to serve a static file from a specified directory. A relative path is associated with each Static File Provider so that requests received on this path are dispatched directly to the file provider and are not mapped to a policy in the usual way. For example, you can configure a Static File Provider to serve c:\my_brand\favicon.ico on Windows when it receives requests on the /favicon.ico relative path. Add a static file provider
To add a Static File Provider to an HTTP Services group (for example, Default Services):
1. Select Environment Configuration > Listeners > API Gateway > Default Services >
Paths.
2. Right-click Paths, and select Add > Static File Provider.
3. Complete the following fields on the General tab.
Relative Path:
Enter the path that you want to receive requests for the static file on (for example, /favicon.ico).
File:
Enter or browse to the location of static file you want to serve (for example, $VDISTDIR/webapps/emc/favicon.ico, where $VDISTDIR specifies the directory where the API Gateway is installed).
HTTP Method:
This tab enables you to configure an accepted HTTP method for the static file. The default is GET, which means that only HTTP GET calls are accepted. You can override the default, and select a different HTTP method for this resolver from the list. For more details, see HTTP method settings on page 311.
Axway API Gateway 7.5.2
Policy Developer Guide 316
8 API Gateway instances
Servlet applications
Developers can write their own Java servlets and deploy them under the API Gateway to serve HTTP traffic. Conversely, they can remove some of the default servlets from the out-of-the-box configuration (for example, to remove the ability to view logging remotely). This pairing down of unwanted functionality may be required to further lock down the machine on which the API Gateway is running. Note
Adding and removing Servlet Applications should be performed only by developers with very specific requirements and under strict guidance from the Axway Support team. These instructions simply outline how to configure the fields on the dialogs used to set up Servlet Applications. For more detailed instructions, contact the Axway Support team. When editing Admin Node Manager or API Gateway Analytics configuration, there are some default Servlet Applications available under the Management Services group. By default, this HTTP Services Group is not displayed, but can be displayed using the Preferences dialog in the Policy Studio. For example, the /configuration/ Servlet Application updates configuration information for the API Gateway.
Caution
Deleting any default Servlet Applications may prevent the API Gateway from functioning correctly. You should only delete default Servlet Applications under strict supervision of Axway Support. Add a servlet application
To add a Servlet Application to an HTTP Services Group (for example, Default Services), perform the following steps:
1. Select Environment Configuration > Listeners > API Gateway > Default Services >
Paths.
2. Right-click Paths, and select Add >Servlet Application.
3. Complete the following fields on the General tab.
Relative Path:
Enter the servlet context in this field. You can add multiple servlets under this context, where each servlet is mapped to a unique URI.
Session Timeout:
Enter the timeout in seconds after which an inactive session is closed. Click OK.
HTTP Method:
This tab enables you to configure an accepted HTTP method (for example, POST). The default is *, which accepts all HTTP methods. You can override the default, and select an appropriate HTTP method for this resolver from the list. For more details, see HTTP method settings on page 311.
Axway API Gateway 7.5.2
Policy Developer Guide 317
8 API Gateway instances
Add a servlet
The new Servlet Application now appears in the Resolvers window. To add a new servlet, rightclick the new Servlet Application, and select Add Servlet. Configure the following fields on the Servlet dialog:
URI:
The path entered maps incoming requests on a particular request URI to the Java servlet class entered in the field below. This path must be unique across all Servlets added under this Servlet Application (servlet context).
Class:
Enter the fully qualified class name of the servlet class. You can add this class to the server runtime by adding the JAR, class file, or package hierarchy to the [VDISTDIR]/ext/lib folder. VDISTDIR is your API Gateway distribution directory, which is the location where the API Gateway is installed. Read Timeout:
Specify the time in seconds that the servlet should wait before closing an idle connection.
Servlet Properties:
You can configure properties for each servlet by clicking the Add button, and entering a name and value in the fields provided on the Properties dialog. Web service resolvers
A web service resolver is used to identify messages destined for a web service, and to map them to the Service Handler (Web Service Filter) for that web service. When you import a WSDL file in the Web Service Repository, a new web service resolver node is created for each imported web service under the Paths for the relevant HTTP services group (for example, Default Services). You can edit the web service resolver settings by right-clicking its tree node, and selecting Edit. The following settings are available in the Web Service Resolver dialog:
Enable this Web service resolver:
Specify whether to enable this web service resolver. This is enabled by default.
Name:
You can edit the name of the web service resolver.
Web service:
Click the browse button to select a web service to resolve to. Defaults to the web service imported into the Web Services Repository when this resolver was created. Policies:
On the Policies tab, select the path and the policies to use for the web service. You can specify a single policy or a chain of policies. Policies are called in the order displayed on this tab. The global request policy, the policy automatically generated when the WSDL file is imported, and the global response policy are all selected in a chain by default. Complete the following fields:
Axway API Gateway 7.5.2
Policy Developer Guide 318
8 API Gateway instances
l Matches the paths in the WSDL:
Select this option if you want the resolver to use the paths specified in the WSDL file. This is the default.
l Matches this path:
Select this option if you want to specify a different path from the WSDL file, and enter the path.
l Global Request Policy:
If a global request policy is configured, when you select this setting, the global request policy is called first in the policy chain. For more details, see Configure global policies on page 76.
l Path Specific Policy:
To configure a path-specific policy, select this setting, and browse to select a policy from the dialog.
l Global Response Policy:
If a global response policy is configured, when you select this setting, the global response policy is called last in the policy chain. For more details, see Configure global policies on page 76.
Policies are only evaluated when selected, and when the policy can be reached. If any selected policy fails, the chain fails, and no more policies are evaluated.
Logging Settings:
The Logging Settings tab enables you to configure the logging level for all filters executed on the web service, and to configure when message payloads are logged. The default logging level for all filters on the web service is Failure. These logging settings are the same as those already described for the relative path. For more details, see Logging settings on page 309. HTTP Method:
The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which means that all HTTP Methods are accepted. You can override the default behavior, and select an appropriate HTTP method from the list. The HTTP Method settings are the same as those already described for the relative path. For more details, see HTTP method settings on page 311. Edit service handler options
You also edit options for the Service Handler for the web service. Right-click the Web Service Resolver node, and select Quick-Edit Policy to display a dialog that enables you to configure the following options:
l Validation:
To use a dedicated validation policy for all messages sent to the web service, select this check box, and click the browse button to configure a policy in the dialog. For example, this enables you to delegate to a custom validation policy used by multiple web services.
l Routing:
To use a dedicated routing policy to send all messages on to the web service, select this check box, and click the browse button to configure a policy in the dialog. For example, this enables you to delegate to a custom routing policy used by multiple web services.
Axway API Gateway 7.5.2
Policy Developer Guide 319
8 API Gateway instances
l WSDL Access Options:
Select whether to make the WSDL for this web service available to clients. The Allow the API
Gateway to publish WSDL to clients check box is selected by default. The published WSDL represents a virtualized view of the web service. Clients can retrieve the WSDL from the API Gateway, generate SOAP requests, and send them to the API Gateway, which routes them on to the web service. These options enable you to configure the underlying autogenerated Service Handler (Web
Service Filter) without navigating to it in the Policies tree. These are the most commonly modified Web Service Filter options after importing a WSDL file. Changes made in this d ialog are visible in the underlying Web Service Filter. For more details, see Web service filter on page 845.
Check URI path syntax in incoming
HTTP requests
You can configure whether to enable strict checking of URI syntax for incoming HTTP requests. If this is enabled, requests with invalid URI path syntax are rejected (the default). If this is disabled, the API Gateway finds the best path match for the URI string.
The main use case for disabling this setting is for compatibility with legacy API Gateway behavior. If you already accept and process client URLs that are not strictly correct, you might want to continue. For example, the Microsoft IIS Web server accepts URLs that contain a backslash character (for example, http://myserver.com\resource). You might want to put an API Gateway in front of your IIS server, and continue to accept these non-standard URLs.
To configure this setting, perform the following steps:
1. Edit the following file:
INSTALL-DIR/apigateway/system/conf/jvm.xml
2. Configure the following setting to true or false as appropriate:
<VMArg name="-Dcom.vordel.strictUriSyntaxChecking=true"/>
The default and recommended setting is true.
Configure WebSocket connections
WebSocket protocol overview
The WebSocket protocol provides an extension to the HTTP 1.1 protocol to establish persistent, bidirectional communication between a client and a server. The WebSocket protocol can be summarized as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 320
8 API Gateway instances
1. To establish a communication channel between a client and a server, the client needs to send an HTTP Upgrade request to the server. This is known as the WebSocket protocol handshake. 2. If the server is capable and willing to upgrade the connection, it sends a HTTP 101 response to the requesting client. At this point the handshake is considered successful and the connection between the server and the client is upgraded to the WebSocket protocol.
Note
As soon as the client receives the HTTP 101 response the connection is no longer considered an HTTP connection.
3. Messages can now flow bidirectionally between the server and the client over the WebSocket connection. 4. Any participant in the data exchange can request the WebSocket connection be terminated by sending a Close request to the other participant. For a detailed description of the protocol, see RFC 6455.
Configure a WebSocket connection
API Gateway can act as a WebSocket proxy, whereby it is deployed in front of a WebSocket capable web server (for example, Jetty or Apache Tomcat) and provides governance (security, monitoring, and so on) on the WebSocket traffic flowing between the client, API Gateway, and the web server.
For a complete example of creating and testing a WebSocket connection, see WebSocket connection example on page 324.
WebSocket configuration settings
Configure the following fields on the WebSocket configuration dialog:
Enable this path resolver:
Select or deselect the check box to enable or disable the WebSocket handler. It is enabled by default. Policies settings
You can assign specific policies on this tab to specific URIs that define the WebSocket endpoints. For example, you might need to handle frames being exchanged between a client and ws://example.org/echo differently to frames being exchanged between a client and ws://example.org/voip. Note
In the above scenario, different sets of policies need to be defined for each URI ( /echo and /voip). This requires different relative paths. For more information on relative paths, see Configure relative paths on page 308.
When a request arrives that matches the path:
Enter the path on which WebSocket connections are to be accepted. This defines the URI of the WebSocket endpoint. A relative path resolver for this path must already exist.
Axway API Gateway 7.5.2
Policy Developer Guide 321
8 API Gateway instances
Default MIME type for message body:
Enter the MIME type of the messages. The default is application/json. When messages are flowing bidirectionally between a WebSocket server and client, they are no longer HTTP messages and as such they do not contain a Content type header. For API Gateway to process the content of the message it needs to know what type of content the message is. This field enables you to specify the type of message being exchanged between the server and the client.
On Upgrade request from client:
Click the browse button to select a policy to be used by API Gateway when an Upgrade request is received. This policy is executed when a connection is being upgraded from HTTP to WebSocket. For example, you might statically route all WebSocket requests to ws://example.org to wss://example.com by using a policy. A policy for an HTTP connection must be provided and this policy must provide a mechanism to connect to the remote server.
For example, to route all requests to ws://example.org to wss://example.com, you can use the Static Router filter. Similarly, for dynamic routing you can use the Dynamic Router or Connect to URL filters. In the latter case, the remote host that the client is attempting to connect to can be extracted from the Host header of the request. This value can then be passed to the Connect to URL filter and used by that filter to establish a connection to the remote host. Note
In the routing filter, you must use http:// or https:// URLs as API Gateway does not recognize ws:// and wss:// URLs. For an example, see WebSocket connection example on page 324.
The on upgrade policy is also a good place to perform authentication and authorization of the requesting client.
On WebSocket communication from client:
Click the browse button to select a policy to be used by API Gateway when frames are received from the WebSocket client. On WebSocket communication from server:
Click the browse button to select a policy to be used by API Gateway when frames are received from the WebSocket server. Note
After a successful upgrade request, the context used to upgrade the connection from HTTP to WebSocket protocol is accessible to the policies called for specific frames. This context is not shared between different WebSocket connections and it is destroyed when the connection is closed. The context contains all the message attributes (including authorization and authentication data) used by the upgrade request. This context should be accessed by the server and client policies in read-only mode. The following figure shows the flow of messages between the client, API Gateway, and the server in a typical WebSocket communication. It also shows at which point each of the API Gateway policies are called. Axway API Gateway 7.5.2
Policy Developer Guide 322
8 API Gateway instances
Connection expire time:
Enter a numerical value and choose the units from the list. The available options are seconds, minutes, hours, and days. The default value is 0, which means unlimited.
This is the absolute time for the connection to be active. For example, if this value is set to 1 hour, then after 1 hour the connection is dropped by API Gateway even if the connection is still active (frames are being sent). Tip
You can define an idle timeout for the connection as a part of the remote host configuration.
Advanced settings
For details on the fields on this tab, see Advanced settings on page 311. CORS settings
For details on the fields on this tab, see CORS settings on page 311. Axway API Gateway 7.5.2
Policy Developer Guide 323
8 API Gateway instances
Monitor a WebSocket connection
You can use the API Gateway Manager web console to monitor WebSocket traffic. You can view the initial HTTP Upgrade request and response on the Traffic > HTTP tab. You can view all the WebSocket frames processed by API Gateway on the Traffic > WebSockets tab.
To view all the WebSocket frames processed by API Gateway in API Gateway Manager, follow these steps:
1. Click the Traffic button at the top of the window.
2. Click the WebSockets tab. A view of all WebSocket frames sent from or received by API Gateway is displayed.
Tip
A message might consist of one or more frames.
3. Click a message frame to see a detailed view of the content. For example, if you click a frame sent from the client to the server, the origin, opcode (interpretation of the payload data), duration, length of the data, key used to mask the data, and payload itself are shown.
For more information on traffic monitoring using the API Gateway Manager web console, see the API Gateway Administrator Guide.
WebSocket connection example
This example shows you how to create and test a WebSocket connection in API Gateway. API Gateway acts as a proxy for WebSocket services.
To create and test a WebSocket connection, perform the following steps:
1. Create a HTTP/1.1 remote host for the back-end WebSocket service. See Create a HTTP/1.1 remote host on page 324.
2. Create a policy to handle the initial Upgrade request from the client. See Create a policy to handle the Upgrade request on page 325.
3. (Optional) Create policies to handle data frames from the client and server. See Create policies to handle data frames on page 327.
4. Create a WebSocket handler. See Create a WebSocket handler on page 327.
5. Test the connection using a WebSocket client. See Test the WebSocket connection on page 328.
Create a HTTP/1.1 remote host
Each WebSocket server that API Gateway is routing to must be defined as an HTTP/1.1 remote host. To add a remote host to an API Gateway instance, right-click the API Gateway instance under Environment Configuration > Listeners in the Policy Studio tree, and select Add Remote
Host. For more information, see Configure remote host settings on page 283.
Axway API Gateway 7.5.2
Policy Developer Guide 324
8 API Gateway instances
In this example, the back-end WebSocket service is provided by a public echo service on the URL http://echo.websocket.org/. The remote host configuration is as follows:
When configuring the remote host:
l Select the Allow HTTP 1.1 check box.
l Set Maximum connections to -1 (unlimited connections).
Create a policy to handle the Upgrade request
This policy handles the Upgrade request from the client. You can also perform authentication and authorization of the requesting client in this policy.
In this example, the sample Upgrade policy contains a simple Connect to URL filter:
The Connect to URL filter is configured as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 325
8 API Gateway instances
Note
The filter points to the URL http://echo.websocket.org/ and not ws://echo.websocket.org. In the URL http:// is used instead of ws:// (and similarly https:// instead of wss://) as API Gateway does not recognize ws:// and wss:// URLs. This works because the upgrade connection is an HTTP call until the WebSocket server returns 101 - switching protocols. Alternatively, you could use a Static Router or Dynamic Router filter in combination with a Connection filter for the Upgrade policy.
Axway API Gateway 7.5.2
Policy Developer Guide 326
8 API Gateway instances
Create policies to handle data frames
These are optional policies that trigger on data frames from the client or server. The policies that trigger on data frames from the client and server do not need to make any connections, as the connection is already established. They can modify the WebSocket frames found in content.body to alter the frame being sent. To access the HTTP headers from the original Upgrade request, you can find a copy of the HeaderSet object inside the websock.context attribute that is available on each invocation (the websock.context attribute should be considered read-only).
This example does not use any policies to handle data frames.
Create a WebSocket handler
To enable API Gateway to accept an HTTP Upgrade request from a client you must add a WebSocket handler to your API Gateway configuration and configure it with the HTTP path that the upgrade can be expected on. To add a WebSocket handler, follow these steps:
1. In the Policy Studio tree, select a list of relative paths (for example, Environment
Configuration > Listeners > API Gateway > Default Services > Paths). 2. In the Resolvers window on the right, click Add > WebSocket to display the WebSocket
configuration dialog. For more information, see WebSocket configuration settings on page 321.
3. Configure the WebSocket as follows:
Note
Ensure that you have not set gzip or deflate compression, as it is not compatible for WebSocket connections. For more information, see Compressed content encoding on page 863.
Axway API Gateway 7.5.2
Policy Developer Guide 327
8 API Gateway instances
Test the WebSocket connection
To test the WebSocket connection, follow these steps:
1. Deploy the configuration on the API Gateway instance. Click the Deploy button on the toolbar in Policy Studio or press F6.
2. Go to https://www.websocket.org/echo.html (a test WebSocket client).
3. Enter the address of your API Gateway WebSocket proxy in the Location field and follow the instructions to connect and send messages. For example:
4. View the traffic in API Gateway Manager. For example:
Configure virtual hosts
Overview
A virtual host is a server, or pool of servers, that can host multiple domain names (for example, company1.api.example.com and company2.api.example.com). This enables you to run more than one website, or set of REST APIs, on a single host machine (for example, 192.0.2.11). Each domain name can have its own host name, paths, APIs, and so on. For example:
https://company1.api.example.com:8080/api/v1/test
https://company2.api.example.com:8080/api/v2/test
https://company3.api.example.com:8080/api/v2/test
Axway API Gateway 7.5.2
Policy Developer Guide 328
8 API Gateway instances
The API Gateway implements name-based virtual hosting, in which the client HTTP Host header is used as the routing criteria during path resolution (for example, Host
company1.api.example.com). This means that you can have multiple domains running on the same hardware (IP address), while this is not apparent to the client or end user.
For example, the following URL invokes the company2.api.example.com virtual host:
https:/company2.api.example.com/api/v1/test
This results in the following message at runtime:
POST /api/v1/test HTTP/1.1
Host:company2.api.example.com
Content-Type:application/x-www-form-urlencoded
client_id=SampleConfidentialApp&client_secret=......
Note
To support name-based virtual hosts, you must first ensure that your Domain Name System (DNS) server has been updated to map each host name to the correct IP address ( for example, *.example.com is mapped to 192.0.2.11). For more details on configuring a DNS service with wildcards for virtual hosting, see the API Gateway Administrator Guide .
When your DNS server has been updated to map each host name to the correct IP address, you can then configure the API Gateway for virtual hosting. Configure virtual hosts for HTTP services
You can configure virtual hosts at the HTTP service level. This means that these settings are applied to the HTTP service and to any child resolvers. To configure a virtual host at the HTTP service level, perform the following steps:
1. In the Policy Studio tree, select an HTTP service (for example, Environment Configuration > Listeners > API Gateway > Default Services > Virtual Hosts).
2. Right-click, and select Add a Virtual Host.
3. Configure the following settings in the Virtual Host dialog:
l Name:
Enter a unique name of the virtual host.
l Enabled:
Select whether the virtual host processing is enabled. This is enabled by default.
l Hosts:
Specify the list of domains that you wish to host under this HTTP service. To add a host, click Add at the bottom right, and enter the domain name (for example company1.api.example.com).
Axway API Gateway 7.5.2
Policy Developer Guide 329
8 API Gateway instances
You can also specify domain names using wildcards already configured in your DNS (for example *.example.com:/8080 or company3.api.example.com.*). For details on configuring DNS wildcards, see the API Gateway Administrator Guide. Configure child resolvers
When you have configured a virtual host at the HTTP service level, you can also configure the following child resolvers:
l Relative path
l Static content provider
l Static file provider
l Servlet application
To configure a child resolver, perform the following steps:
1. In the Policy Studio tree, select the Paths node under the virtual host, and right-click to add a resolver (for example, Add relative path).
2. In the Resolve path to policies dialog, click the browse button beside the Path Specific
Policy field, and select a policy to run on this path.
For example, if an inbound request to /Healthcheck matches on company1.api.*, the Company1 Health Check policy is executed. Otherwise, the global Health Check policy for the HTTP service is executed (in this case, Default Services).
Configure virtual hosts for REST APIs
When API Manager has been installed, you can also configure virtual hosts for specific REST APIs. By default, the HTTP service-level profile is used, but you can override the virtual host at the REST API level. For example, when adding a new REST API in the New Rest API dialog, you can specify virtual hosts on the Exposure tab. In the Virtual Host field, click the browse button to select a virtual host in the dialog. Tip
The virtual hosts listed are automatically filtered based on the HTTP service selected on the Exposure window (for example, Default Services ). If no virtual host has already been configured, right-click the HTTP service node (for example, Default Services), and select Add a Virtual Host. For more details on virtual host settings, see Configure virtual hosts for HTTP services on page 329.
Axway API Gateway 7.5.2
Policy Developer Guide 330
8 API Gateway instances
In addition, when editing an existing REST API, you can also specify a virtual host in the Edit Rest
API dialog. Finally, when the API has been created, you can view it in the Resolver screen for its virtual host. The following shows a simple Flickr API example:
For more details on configuring REST APIs and methods, see the API Manager API Management Guide.
Configure SMTP services
Overview
The API Gateway provides support for Simple Mail Transfer Protocol (SMTP), which enables the API Gateway to receive email and to act as a mail relay. The API Gateway can accept incoming email messages using the SMTP protocol, and then forward them on to a configured mail server. You can also use Policy Studio to configure optional policies for specific SMTP commands (for example, HELO/EHLO, AUTH , MAIL FROM, and so on).
When an SMTP command is configured in Policy Studio, each time the SMTP command is accepted by the API Gateway, the appropriate policy is executed. When the policy completes successfully, the SMTP conversation resumes. This topic shows how to configure SMTP services, interfaces, and handler policies using Policy Studio. Axway API Gateway 7.5.2
Policy Developer Guide 331
8 API Gateway instances
Add an SMTP service
To add an SMTP service to enable the API Gateway to accept SMTP connections, perform the following steps in Policy Studio:
1. Under the Environment Configuration > Listeners node in the tree, select an API Gateway instance node (for example, the default API Gateway). 2. Right-click, and select Add SMTP Services.
3. In the SMTP Services dialog, specify a unique name for the SMTP service in the Name field.
4. In the Outgoing Server Settings section, complete the following settings:
l Host
Host name or IP address of the remote mail server. This is the server to which the API Gateway forwards incoming SMTP commands (for example, smtp.gmail.com). You can also specify a mail server running locally on the same machine as the API Gateway using an address of localhost or 127.0.0.1.
l Port
Port on which to connect to the remote mail server. Defaults to port 25.
5. In the Security section, complete the following settings:
l Connection Security
Select the type of security used for the connection to the remote mail server. Defaults to None. Other possible values are SSL and STARTTLS. l Trusted Certificates
Use this tab to select the trusted CA certificates used in the security handshake for the connection to the remote mail server. This field is mandatory if SSL or STARTTLS connection security is selected.
l Client SSL Authentication
Use this tab to specify the trusted client certificates used in the security handshake for the connection to the remote mail server. This field is optional if SSL or STARTTLS connection security is selected.
l Advanced
Use this tab to specify a list of ciphers to use during the security handshake for the connection to the remote mail server. Defaults to DEFAULT. For more details, see the OpenSSL ciphers man page. This field is optional if SSL or STARTTLS connection security is selected.
Axway API Gateway 7.5.2
Policy Developer Guide 332
8 API Gateway instances
6. In the Authentication section, complete the following settings:
l Username
Specify the user name used to authenticate the API Gateway with a remote SMTP server using the AUTH SMTP command. For more details, see SMTP authentication on page 340.
l Password
Specify the password used to authenticate the API Gateway with a remote SMTP server using the AUTH SMTP command. For more details, see SMTP authentication on page 340.
7. Select the Include in real time monitoring check box to monitor the SMTP services using the web-based API Gateway Manager and API Gateway Analytics monitoring consoles.
8. Click OK. This creates a tree node for the SMTP service under the selected instance in the Services tree.
Add an SMTP interface
When you have configured the outbound SMTP protocol, you must then set up an inbound interface to accept client connections. You can choose from the following interface types:
TCP
Non-secure connection. All traffic is sent in-the-clear.
SSL
SSL handshake is performed at connection time, so the entire SMTP conversation is secure.
STARTTLS
Initial connection is in the clear. The API Gateway advertises STARTTLS during the initial SMTP HELO/EHLO handshake. If the client supports this, it can send a STARTTLS command to the API Gateway, which in turn promotes connection security, and upgrades the connection to SSL/TLS.
Because the SSL and STARTTLS interface types have the potential to be secure (STARTTLS starts off non-secure, but can be upgraded during the SMTP conversation), a common configuration window is used for both protocols in Policy Studio. To configure an inbound interface, perform the following steps in Policy Studio:
1. Under the Environment Configuration > Listeners node in the tree, select the SMTP node under the instance. 2. Right-click, and select Add Interface > interface type (TCP, SSL, or STARTTLS).
3. Complete the settings on the relevant dialog. For full details on these settings, see Configure HTTP services on page 290.
4. Click OK.
Axway API Gateway 7.5.2
Policy Developer Guide 333
8 API Gateway instances
Configure policy handlers for SMTP commands
You can use Policy Studio to configure optional policy handlers for each of the following SMTP commands:
l HELO/EHLO
l AUTH
l MAIL FROM
l RCPT TO
l DATA
The next sections explain how to configure policy handlers for each command.
Add an HELO/EHLO policy handler
The HELO/EHLO policy handler is invoked when a HELO/EHLO SMTP command is received from a client. This handler enables you to modify the HELO/EHLO greeting and the client domain. You can configure the greeting message sent back to the client from the API Gateway during the HELO/EHLO handshake as required. You can also configure a policy to replace the value of smtp.helo.greeting. The domain specified by the connected client in the HELO/EHLO command can be modified before forwarding on to the remote mail server. You can also configure a policy to replace the value of smtp.helo.domain. To configure a policy handler for the HELO/EHLO command, perform the following steps:
1. Under the Environment Configuration > Listeners node in the tree, select the SMTP node under the instance. 2. Right-click, and select Add Policy Handler > HELO/EHLO.
3. In the Configure HELO Host dialog, specify the Greeting to be sent back to the client as part of the HELO/EHLO handshake. Defaults to Hello ${smtp.helo.domain}.
4. In the Policy tree, select the policy that you wish to handle the HELO/EHLO command. 5. Click OK.
Message attributes
The following message attributes are generated during processing:
Message Attribute
Description
smtp.helo.domain
The client domain specified in the HELO/EHLO SMTP command received from the client.
Axway API Gateway 7.5.2
Policy Developer Guide 334
8 API Gateway instances
Message Attribute
Description
smtp.helo.greeting
The HELO greeting to be sent back to the client after HELO/EHLO processing is performed. The default value is Hello ${smtp.helo.domain}.
message.source
The inbound port on which SMTP traffic is received by the API Gateway.
message.protocol.type
The protocol used for the connection. This can be smtp-
tcp or smtp-ssl.
monitoring.enabled
Set to true if monitoring is enabled for the protocol, otherwise false.
Add an AUTH policy handler
The AUTH policy handler is invoked when an AUTH SMTP command is received from a client. You can use the AUTH handler to run a policy to perform user authentication checks. For example, during the Authentication phase of the SMTP conversation, the client-supplied username and password can be verified against an Authentication Repository using a policy containing an Attribute Authentication filter. For details on possible authentication scenarios, see SMTP authentication on page 340.
To configure a policy handler for the AUTH command, perform the following steps:
1. Under the Environment Configuration > Listeners node in the tree, select the SMTP node under the instance. 2. Right-click, and select Add Policy Handler > AUTH.
3. In the Configure AUTH dialog, in the Policy tree, select the policy that you wish to handle the AUTH command. 4. Click OK.
Message attributes
The following message attributes are generated during processing:
Message Attribute
Description
authentication.subject.id
The user name supplied by the client.
authentication.subject.password
The password supplied by the client.
message.source
The inbound port on which SMTP traffic is received by the API Gateway.
Axway API Gateway 7.5.2
Policy Developer Guide 335
8 API Gateway instances
Message Attribute
Description
message.protocol.type
The protocol used for the connection. This can be smtp-tcp or smtp-ssl.
monitoring.enabled
Set to true if monitoring is enabled for the protocol, otherwise false.
Add a MAIL policy handler
The MAIL policy handler is invoked when a MAIL FROM SMTP c ommand is received from a client. Emails can be rejected based on wildcard matching of the supplied sender address in the MAIL
FROM SMTP command. For example, email addresses containing GMAIL.COM ( fromAddress of *@gmail.com) as the domain could be accepted using a simple True filter. Whereas, email addresses containing YAHOO.COM ( fromAddress of *@yahoo.com) could be rejected using a simple False filter. To configure a policy handler for the MAIL FROM command, perform the following steps:
1. Under the Environment Configuration > Listeners node in the tree, select the SMTP node under the instance. 2. Right-click, and select Add Policy Handler > MAIL.
3. In the Configure MAIL Address dialog, you must specify the From Address. This is an email address used to filter addresses specified in the MAIL FROM SMTP command. You can specify this as a wildcard. The following are some example values:
From Address
Description
*
Runs the policy for any email address received.
*@gmail.com
Runs the policy for all email addresses with the gmail.com domain.
S*@axway.*
Runs the policy for all email addresses with any axway domain, and beginning with the letter s.
The policy selection is performed on a best-match basis. 4. In the Policy tree, select the policy that you wish to handle the MAIL FROM command. 5. Click OK.
You can configure multiple MAIL handlers so that different policies are executed, depending on the received mail address. Message attributes
The following message attributes are generated during processing:
Axway API Gateway 7.5.2
Policy Developer Guide 336
8 API Gateway instances
Message Attribute
Description
smtp.helo.domain
The client domain specified in the HELO/EHLO SMTP command received from the client.
smtp.mail.from
The email address specified in the MAIL FROM SMTP command received from the client.
message.source
The inbound port on which SMTP traffic is received by the API Gateway.
message.protocol.type
The protocol used for the connection. This can be smtp-
tcp or smtp-ssl.
monitoring.enabled
Set to true if monitoring is enabled for the protocol, otherwise false.
Add a RCPT policy handler
The RCPT policy handler is invoked when a RCPT TO SMTP command is received from a client. You can use this handler to filter addresses specified in the RCPT TO SMTP command. Recipients can be rejected based on wildcard matching of the supplied recipient address in the RCPT SMTP command. For example, recipient addresses containing GMAIL.COM ( toAddress of *@gmail.com) as the domain could be accepted using a simple True filter. Whereas, addresses containing YAHOO.COM ( toAddress of *@yahoo.com) could be rejected using a simple False filter. You can configure multiple RCPT handlers so that different policies are executed, depending on the received email address. To configure a policy handler for the RCPT TO command, perform the following steps:
1. Under the Environment Configuration > Listeners node in the tree, select the SMTP node under the instance.
2. Right-click, and select Add Policy Handler > RCPT.
3. In the Configure Recipient Address dialog, you must specify the To Address. This is an email address used to filter addresses specified in the RCPT TO SMTP command. You can specify this as a wildcard. The following are some example values:
To Address
Description
*
Runs the policy for any email address received.
*@axway.com
Runs the policy for all email addresses with the axway.com domain.
Axway API Gateway 7.5.2
Policy Developer Guide 337
8 API Gateway instances
To Address
Description
d*@yahoo.*
Runs the policy for all email addresses with any yahoo domain, and beginning with the letter d. The policy selection is performed on a best-match basis. 4. In the Policy tree, select the policy that you wish to handle the MAIL FROM command. 5. Click OK.
Message attributes
The following message attributes are generated during processing:
Message Attribute
Description
smtp.helo.domain
The client domain specified in the HELO/EHLO SMTP command received from the client.
smtp.mail.from
The email address specified in the MAIL FROM SMTP command received from the client.
smtp.rcpt.to
The email address specified in the RCPT TO SMTP command received from the client. Note
smtp.rcpt.recipients
This is the current recipient being processed, whereas smtp.rcpt.recipients is the list of recipients processed so far.
The list (collection of strings) of recipients (email addresses) received or processed so far b y the SMTP transaction. This is read-only and updated by the API Gateway each time it receives a RCPT TO command from the client. message.source
The inbound port on which SMTP traffic is received by the API Gateway.
message.protocol.type
The protocol used for the connection. This can be smtp-
tcp or smtp-ssl.
monitoring.enabled
Set to true if monitoring is enabled for the protocol, otherwise false.
Axway API Gateway 7.5.2
Policy Developer Guide 338
8 API Gateway instances
Add a DATA policy handler
The DATA policy handler is invoked when a DATA SMTP c ommand is received from a client. For example, for emails that contain SOAP/XML content, you can add an XML signature to the XML data, stored in the content.body message attribute, using an XML Signature Generation filter. For emails containing attachments, the attached mail data can be run through one of the API Gateway anti-virus filters. Alternatively, you can use SMIME Encrypt or SMIME Decrypt filters to encrypt or decrypt emails (including attachments) passing through the API Gateway. You can also digitally sign emails using an SMIME Sign filter, or verify signatures on already digitally signed emails using an SMIME
Verify filter. To configure a policy handler for the DATA command, perform the following steps:
1. Under the Environment Configuration > Listeners node in the tree, select the SMTP node under the instance.
2. Right-click, and select Add Policy Handler > DATA.
3. In the Policy tree, select the policy that you wish to handle the DATA command. 4. Click OK.
Message attributes
The following message attributes are added during processing:
Message Attribute
Description
smtp.helo.domain
The client domain specified in the HELO/EHLO SMTP command received from the client.
smtp.mail.from
The email address specified in the MAIL FROM SMTP command received from the client.
smtp.rcpt.recipients
The full list (collection of strings) of recipients (email addresses) processed by the SMTP transaction.
content.body
The stream representing the body of the mail. Note
The content.body does not include MIME headers.
message.source
The inbound port on which SMTP traffic is received by the API Gateway.
message.protocol.type
The protocol used for the connection. This can be smtp-
tcp or smtp-ssl.
Axway API Gateway 7.5.2
Policy Developer Guide 339
8 API Gateway instances
Message Attribute
Description
monitoring.enabled
Set to true if monitoring is enabled for the protocol, otherwise false.
SMTP authentication
The SMTP protocol supports Extended SMTP (ESMTP) PLAIN authentication. The following matrix shows the possible authentication scenarios and actions based on the SMTP Services configuration:
Scenario
AUTH
handler
AUTH user
name and
password
Mail
server
advertises
AUTH
API
Gateway
advertises
AUTH
Proxy
client
AUTH
Authenticate
API Gateway
to server
1
No
No
No
No
No
No
2
No
No
Yes
Yes
Yes
No
3
No
Yes
No
No
No
No
4
No
Yes
Yes
No
No
Yes
5
Yes
No
No
Yes
No
No
6
Yes
No
Yes
Yes
No
No
7
Yes
Yes
No
Yes
No
No
8
Yes
Yes
Yes
Yes
No
Yes
These authentication scenarios are described as follows:
1. No authentication user name and password are specified so the API Gateway does not attempt to authenticate with the server. The server does not support authentication anyway. The mail server does not advertise authentication so the API Gateway does not advertise AUTH to the client. The client authentication is not proxied because the server does not support it.
2. No authentication user name and password are specified so the API Gateway does not attempt to authenticate with the server. The server does not support authentication anyway. The mail server advertises AUTH, so the API Gateway advertises AUTH to the client. No AUTH handler is configured, so the client authentication details are proxied to the server. 3. Same as 1 above.
Axway API Gateway 7.5.2
Policy Developer Guide 340
8 API Gateway instances
4. The authentication user name and password are specified so the API Gateway authenticates with the server. The mail server advertises AUTH, but because a user name and password are specified, the API Gateway does not advertise AUTH to the client because the API Gateway authenticates with the server using the configured credentials. This also implies no client authentication proxying.
5. No authentication user name and password are specified so the API Gateway does not attempt to authenticate with the server. The server does not support authentication anyway. AUTH handler configured, which implies the API Gateway performs authentication, so advertise AUTH to the client.
6. Same as 5 above.
7. AUTH handler configured, which implies the API Gateway performs authentication, so advertise AUTH to the client. No proxying occurs because the API Gateway performs the authentication. No authentication is performed with the server because the server does not support it.
8. AUTH advertised to the client because the API Gateway performs authentication (and the mail server supports it). AUTH handler configured, which implies the API Gateway performs authentication. No proxying occurs because the API Gateway performs the authentication. Authentication is performed with the server because the server supports AUTH and a user name and password is configured. SMTP Content-Transfer-Encoding
The SMTP protocol supports automatic Content-Transfer-Encoding/Decoding. For DATA SMTP commands, the content of the incoming mail body may be encoded. To enable policy filters to view and/or manipulate the raw body data, the contents are automatically decoded before policy execution, and re-encoded afterwards (before being forwarded on to the configured outbound mail server).
Supported encodings
The following encodings are supported:
l Base64
l 7-bit
l 8-bit
l quoted-printable
l binary
However, Base64 is the only encoding that results in decoding/re-encoding of the mail data.
Multipart MIME content, generally used for sending attachments in SMTP, is also supported. Each separate body in the multipart is checked for a Content-Transfer-Encoding, and the decoding/reencoding is performed as appropriate. Axway API Gateway 7.5.2
Policy Developer Guide 341
8 API Gateway instances
Deployment example
This section provides a step-by-step example of how to configure and deploy SMTP services using the API Gateway. In this example, the API Gateway acts as a relay between a Thunderbird email client and the Google Gmail service. Configure the API Gateway SMTP services
The API Gateway connects to the Gmail STARTTLS interface, which is available at smtp.gmail.com, and listening on port 587.To configure the SMTP Services, perform the following steps in Policy Studio:
1. Under the Environment Configuration > Listeners node in the tree, select a Process node (for example, the default API Gateway). 2. Right-click, and select Add SMTP Services.
3. Enter smtp.gmail.com for the Host.
4. Enter 587 for the Port.
5. Select STARTTLS from the Connection Security drop-down list. This is selected because smtp.gmail.com:587 exposes the Gmail STARTTLS SMTP interface.
6. Because STARTTLS has the potential to be upgraded to a secure connection, you must also select some Trusted Certificates.
7. Accept all other defaults, and click OK to add the SMTP services.
Configure the SMTP client interface
To configure a STARTTLS client interface, perform the following steps in Policy Studio:
1. Right-click the SMTP Services node, and select Add Interface > STARTTLS. 2. Enter a Port (for example, 8026). This is the port on which the API Gateway’s incoming SMTP traffic is accepted. You can enter any port that is not already in use.
3. Because STARTTLS has the potential to be upgraded to a secure connection, you must configure a trusted certificate. Click the X.509 Certificate button.
4. Select a certificate in the Select Certificate dialog.
5. Click OK to return to the Configure STARTTLS Interface dialog.
6. When the certificate has been configured, accept all other defaults, and click OK to add the incoming STARTTLS interface.
When the SMTP services and STARTTLS client interface have been configured, you must deploy the changes to the API Gateway.
Axway API Gateway 7.5.2
Policy Developer Guide 342
8 API Gateway instances
Configure Thunderbird client settings
This example uses Thunderbird as the email client. However, you can use any standard email client that supports SMTP. Thunderbird is available as a free download from http://www.mozillamessaging.com/.
To configure a STARTTLS outgoing server in your Thunderbird client, perform the following steps:
1. Launch the Thunderbird email client.
2. From the main menu, select Tools > Account Settings.
3. Expand the Local Folders tree node in the left pane.
4. Select the Outgoing Server node to create a new outgoing server configuration.
5. Click Add to display the SMTP Server dialog.
6. Enter Axway API Gateway [STARTTLS] in the Description field.
7. Enter localhost (or the IP Address of the machine on which the API Gateway service is running) in the Server Name field.
8. Enter 8026 in the Port field. This sends SMTP traffic to the STARTTLS interface configured above, so the ports must match.
9. Select STARTTLS from the Connection security drop-down list. Traffic on this connection may be upgraded to secure during the SMTP conversation.
10. Select Normal Password from the Authentication method drop-down list. This indicates that Authentication is to be performed.
11. Enter a valid Gmail user-name for the User Name.
12. Click OK to add the new outgoing server configuration.
Configure certificates in Thunderbird
To enable Thunderbird to successfully negotiate the STARTTLS conversation with the API Gateway, you must import a CA certificate into Thunderbird. This is also because a certificate was already generated and imported into the API Gateway when configuring its STARTTLS client interface.
To configure a STARTTLS outgoing server in your Thunderbird client, perform the following steps:
1. From the Thunderbird main menu, select Tools > Options.
2. Select the Certificates tab.
3. Click the View Certificates button, to display the Certificate Manager dialog.
4. Click Import, and import the appropriate CA certificate.
5. Click OK when finished.
Axway API Gateway 7.5.2
Policy Developer Guide 343
8 API Gateway instances
Test the STARTTLS client interface
To test the STARTTLS client interface using Thunderbird, perform the following steps:
1. Launch the Thunderbird email client, and create a new mail message.
2. Enter a valid Gmail address in the To field.
3. Enter API Gateway Test as the Subject.
4. Enter This mail has been sent using Axway API Gateway in the mail body.
5. To specify the appropriate outgoing mail server, select Tools > Account Settings from the main menu.
6. Select Axway API Gateway [STARTTLS] - localhost from the Outgoing
Server drop-down list.
7. Click OK.
8. Send the mail.
The following example from the API Gateway trace shows the SMTP commands that occur. Commands marked in bold text shows traffic from the Thunderbird client to the API Gateway and vice versa. Commands marked in italic text shows traffic from the API Gateway to the Gmail server at smtp.gmail.com:587, and vice versa. DEBUG 14:46:46:546 [14b4] incoming call on interface *:8026 from 127.0.0.1:1487
DEBUG 14:46:46:546 [14b4] new connection 08133248, settings source incoming
interface
(force 1.0=no, idleTimeout=60000, activeTimeout=60000)
DATA 14:46:46:546 [14b4] snd 0018: <220 doejAxway>
DATA 14:46:46:562 [14b4] rcv 18: <EHLO [127.0.0.1]>
DEBUG 14:46:46:562 [14b4] 080BE260: new connection cache set SMTP Client
DEBUG 14:46:46:562 [159c] idle connection monitor thread running
DEBUG 14:46:46:562 [14b4] new endpoint smtp.gmail.com:587
DEBUG 14:46:46:640 [14b4] Resolved smtp.gmail.com:587 to:
DEBUG 14:46:46:640 [14b4] 209.85.227.109:587
DEBUG 14:46:46:718 [14b4] connected to 209.85.227.109:587
DEBUG 14:46:46:718 [14b4] new connection 08135BA0, settings source service-wide
defaults (force 1.0=no, idleTimeout=15000, activeTimeout=30000)
DATA 14:46:46:765 [14b4] rcv 44: <220 mx.google.com ESMTP v11sm7979387weq.40>
DATA 14:46:46:765 [14b4] snd 0018: <ehlo [127.0.0.1]>
DATA 14:46:46:812 [14b4] rcv 125: <250-mx.google.com at your service,
[87.198.245.194]
250-SIZE 35651584
Axway API Gateway 7.5.2
Policy Developer Guide 344
8 API Gateway instances
250-8BITMIME
250-STARTTLS
250 ENHANCEDSTATUSCODES>
DATA 14:46:46:812 [14b4] snd 0010: <starttls>
DATA 14:46:46:843 [14b4] rcv 30: <220 2.0.0 Ready to start TLS>
DEBUG 14:46:46:843 [14b4] push SSL protocol on to connection
DEBUG 14:46:46:906 [14b4] No SSL host name provided: using default certificate for
interface
DEBUG 14:46:46:906 [14b4] verifyCert: preverify=1, depth=2, subject /C=US/O=Equifax/
OU=Equifax Secure Certificate Authority, issuer /C=US/O=Equifax/OU=Equifax Secure
Certificate Authority
DEBUG 14:46:46:906 [14b4] ca cert? 1
DEBUG 14:46:46:906 [14b4] verifyCert: preverify=1, depth=1, subject /O=Google
Inc/CN=Google Internet Authority, issuer /C=US/O=Equifax/OU=Equifax Secure
Certificate
Authority
DEBUG 14:46:46:906 [14b4] verifyCert: preverify=1, depth=0, subject
/C=US/ST=California/L=Mountain View/O=Google Inc/CN=smtp.gmail.com,
issuer /C=US/O=Google Inc/CN=Google Internet Authority
DEBUG 14:46:46:952 [14b4] negotiated SSL cipher "RC4-MD5",session 00000000 (not
reused)
DATA 14:46:46:952 [14b4] snd 0018: <ehlo [127.0.0.1]>
DATA 14:46:46:999 [14b4] rcv 140: <250-mx.google.com at your service,
[87.198.245.194]
250-SIZE 35651584
250-8BITMIME
250-AUTH LOGIN PLAIN XOAUTH
250 ENHANCEDSTATUSCODES>
DATA 14:46:46:999 [14b4] snd 0109: <250-AxwayAPI Gateway Hello [127.0.0.1]
250-SIZE 35651584
250-8BITMIME
250-STARTTLS
250 ENHANCEDSTATUSCODES>
DEBUG 14:46:46:999 [14b4] delete transaction 0B95D2C0 on connection 08133248
DATA 14:46:46:999 [14b4] rcv 10: <STARTTLS>
DATA 14:46:46:999 [14b4] snd 0014: <220 Go ahead>
DEBUG 14:46:46:999 [14b4] push SSL protocol on to connection
DEBUG 14:46:46:999 [14b4] Servername CB: SSL host name: localhost, not in host map using default certificate for interface
DEBUG 14:46:47:031 [14b4] negotiated SSL cipher "AES256-SHA", session 00000000
(not reused)
DATA 14:46:47:031 [14b4] rcv 18: <EHLO [127.0.0.1]>
DATA 14:46:47:031 [14b4] snd 0018: <ehlo [127.0.0.1]>
DATA 14:46:47:077 [14b4] rcv 140: <250-mx.google.com at your service,
[87.198.245.194]
250-SIZE 35651584
250-8BITMIME
250-AUTH LOGIN PLAIN XOAUTH
Axway API Gateway 7.5.2
Policy Developer Guide 345
8 API Gateway instances
250 ENHANCEDSTATUSCODES>
DATA 14:46:47:077 [14b4] snd 0124: <250-AxwayAPI Gateway Hello [127.0.0.1]
250-SIZE 35651584
250-8BITMIME
250-AUTH LOGIN PLAIN XOAUTH
250 ENHANCEDSTATUSCODES>
DEBUG 14:46:47:077 [14b4] delete transaction 0B95D2C0 on connection 08133248
DATA 14:46:47:077 [14b4] rcv 41: <AUTH PLAIN ADGzaHllaDe0SHF1ex2r82Su555=>
DATA 14:46:47:077 [14b4] snd 0041: <auth PLAIN ADGzaHllaDe0SHF1ex2r82Su555=>
DATA 14:46:47:718 [14b4] rcv 20: <235 2.7.0 Accepted>
DATA 14:46:47:718 [14b4] snd 0020: <235 2.7.0 Accepted>
DATA 14:46:47:718 [14b4] rcv 45: <MAIL FROM:<[email protected]> SIZE=444>
DATA 14:46:47:718 [14b4] snd 0036: <mail from:<[email protected]>>
DATA 14:46:47:765 [14b4] rcv 33: <250 2.1.0 OK v11sm7979387weq.40>
DATA 14:46:47:765 [14b4] snd 0033: <250 2.1.0 OK v11sm7979387weq.40>
DATA 14:46:47:765 [14b4] rcv 30: <RCPT TO:<[email protected]>>
DATA 14:46:47:765 [14b4] snd 0030: <rcpt to:<[email protected]>>
DATA 14:46:47:812 [14b4] rcv 33: <250 2.1.5 OK v11sm7979387weq.40>
DATA 14:46:47:812 [14b4] snd 0033: <250 2.1.5 OK v11sm7979387weq.40>
DATA 14:46:47:812 [14b4] rcv 6: <DATA>
DATA 14:46:47:812 [14b4] snd 0006: <data>
DATA 14:46:48:609 [14b4] rcv 34: <354 Go ahead v11sm7979387weq.40>
DATA 14:46:48:609 [14b4] snd 0008: <354 OK>
DATA 14:46:48:609 [14b4] rcv 447: <Message-ID: <[email protected]>
Date: Fri, 15 Oct 2010 14:46:46 +0100
From: John Doe <[email protected]>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-GB; rv:1.9.2.9)
Gecko/20100915
Thunderbird/3.1.4
MIME-Version: 1.0
To: [email protected]
Subject: API Gateway Test
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
This mail has been sent via an Axway API Gateway
.>
DATA 14:46:48:609 [14b4] snd 0442: <Message-ID: <[email protected]>
Date: Fri, 15 Oct 2010 14:46:46 +0100
From: John Doe <[email protected]>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-GB; rv:1.9.2.9)
Gecko/20100915
Thunderbird/3.1.4
MIME-Version: 1.0
To: [email protected]
Subject: API Gateway Test
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
This mail has been sent via an Axway API Gateway>
DATA 14:46:48:609 [14b4] snd 0005: <.>
DATA 14:46:49:874 [14b4] rcv 44: <250 2.0.0 OK 1287150409 v11sm7979387weq.40>
DATA 14:46:49:874 [14b4] snd 0044: <250 2.0.0 OK 1287150409 v11sm7979387weq.40>
Axway API Gateway 7.5.2
Policy Developer Guide 346
8 API Gateway instances
DEBUG 14:46:49:874 [14b4] delete transaction 0B95D2C0 on connection 08133248
DATA 14:46:49:874 [14b4] rcv 6: <QUIT>
DATA 14:46:49:874 [14b4] snd 0006: <quit>
DATA 14:46:49:921 [14b4] rcv 49: <221 2.0.0 closing connection v11sm7979387weq.40>
DEBUG 14:46:49:921 [14b4] delete transaction 08040BD8 on connection 08135BA0
DATA 14:46:49:921 [14b4] snd 0049: <221 2.0.0 closing connection v11sm7979387weq.40>
DEBUG 14:46:49:921 [14b4] delete transaction 0B95D2C0 on connection 08133248
DEBUG 14:46:49:921 [14b4] delete connection 08133248, current transaction 00000000
Configure a file transfer service
Overview
The API Gateway can act as a file transfer service that listens on a port for remote clients to connect to it. The API Gateway file transfer service supports the following protocols:
l FTP: File Transfer Protocol
l FTPS: FTP over Secure Sockets Layer (SSL)
l SFTP: Secure Shell (SSH) File Transfer Protocol
For all file transfer protocols, you must configure a file upload policy and an authentication policy. For FTP and FTPS, you must configure a password authentication policy. While for SFTP, you can configure a password authentication policy or a public key authentication policy. The API Gateway can also restrict access to the server based on IP address. When a file transfer service is configured, users are presented with a personal file system view when they log in. The root of this file system is specified in a configurable request directory. Any files they upload are processed by the file upload policy. If this policy succeeds, the output of the policy is stored in a configurable response directory. If the policy fails, the original file is moved to a configurable quarantine directory.
Configuring a file transfer service can be useful when integrating with Business-to-Business (B2B) partner destinations or with legacy systems. For example, instead of making drastic changes to either system, the other system can upload files to the API Gateway. The added benefit is that the file transfer can be controlled and secured using API Gateway policies designed to suit system needs. Tip
For details on how to use the API Gateway to poll a remote file server, to query and retrieve files to be processed, see Configure an FTP poller on page 354.
General settings
You can configure the following settings in the General section:
Axway API Gateway 7.5.2
Policy Developer Guide 347
8 API Gateway instances
Name:
Enter an appropriate name for the file transfer service.
Service Type:
Select the file transfer protocol type for this service from the drop-down list ( ftp, ftps, or sftp). Defaults to ftp.
Implicit:
This setting applies to FTPS only. When selected, security is automatically enabled as soon as the remote client makes a connection to the file transfer service. No clear text is passed between the client and server at any time. In this case, the file transfer service defines a specific port for the remote client to use for secure connections ( 990). This setting is not selected by default.
Explicit:
This setting applies to FTPS only. When selected, the remote client must explicitly request security from the file transfer server, and negotiate the required security. If the client does not request security, the file transfer server can allow the client to continue insecure or refuse and/or limit the connection. This setting is selected by default.
Binding Address:
Enter a network interface to bind to. Defaults to *, which means bind to all available network interfaces on the host on which the API Gateway is installed. You can enter an IP address to bind to a specific network interface.
Port:
Enter a file transfer port to listen on for remote clients to connect to. Defaults to 21.
Note
The API Gateway must execute with superuser privileges to bind to a port number less than 1024 on UNIX/Linux.
File upload settings
For all file transfer protocols, you must specify a File Upload policy to be invoked with the file data. This enables files and directories to be uploaded to a user subdirectory of the Request
Directory . For example, files uploaded by user fred are placed in ${environment.VINSTDIR}/filetransfer/in/persistent/fred, where VINSTDIR is the location of the running API Gateway instance. The specified policy is then invoked with the raw file data. If this policy returns true, the output is placed in the corresponding Response Directory. If this policy returns false or an exception is thrown, the uploaded file is moved to the Quarantine Directory. You can configure the following settings in the File Upload section:
Request Directory:
Specifies the directory into which files and directories are uploaded. Defaults to ${environment.VINSTDIR}/file-transfer/in/. Delete File on Successful Response:
Select whether to delete the uploaded files from the Request Directory when successfully processed. This setting is not selected by default.
Axway API Gateway 7.5.2
Policy Developer Guide 348
8 API Gateway instances
Response Directory:
Specifies the name of the directory in which files output by the API Gateway processing of uploaded files are placed if the File Upload policy returns true. Defaults to out. The original files remain in the Request Directory. Response Suffix:
Specifies the file name suffix that is appended to the output files in the Response Directory. Defaults to .resp.${id}, which enables a unique suffix to be appended to the files.
Quarantine Directory:
Specifies the directory into which the uploaded files are moved if the File Upload policy returns false, or an exception is thrown. Defaults to quarantine.
Note
The response and quarantine directories can be relative or absolute. Relative directories reside under the request directory. The user can manage the uploaded files using their file transfer session (for example, by accessing API Gateway file processing results). Absolute directories must reside outside of the request directory. The user cannot view or manage uploaded files using their file transfer session. Specifying absolute directories hides API Gateway file processing from the user. In this way, the request directory can be seen as the user's home directory for the duration of the connection. Therefore, anything created under the same home directory is visible to the user. However, if the response is created outside this directory (for example, in /tmp/response), the files are not visible to the user.
Specify a file upload policy
You must specify a File Upload policy to be invoked with the raw file data. Perform the following steps:
1. Click the Add button to display the dialog.
2. In the Pattern field, select or enter a regular expression to match against the file name. For example, the following expression means that the configured policy is run against these files types only:
([^\s]+(\.(?i)(xml|xhtml|soap|wsdl|asmx))$)
3. In the Policy field, click the browse button on the right to select a policy, and click OK.
4. Click OK to display the configured pattern and policy in the table.
Message attributes
The File Upload policy uses the following message attributes:
l content.body: Raw message file content.
l file.src.name: Filename of the uploaded file.
l file.src.path: Full file path of the uploaded file.
Axway API Gateway 7.5.2
Policy Developer Guide 349
8 API Gateway instances
Secure services settings
On the Secure Services tab, you can configure the following Client Authentication policies:
Password Authentication Policy:
For FTP and FTPS, you must configure a Password Authentication Policy. Click the browse button on the right to select a configured policy. This policy uses the authentication.subject.id and authentication.subject.password message attributes, which store the user name and password entered by the client user.
Public Key Authentication Policy:
For SFTP, you can configure a Public Key Authentication Policy or Password
Authentication Policy. Click the browse button on the right to select a configured policy. This policy uses the authentication.subject.id and authentication.subject.public.key message attributes, which store the user name and public key used by the client.
You can configure the following Server Authentication settings:
Server Certificate:
For FTPS or SFTP, click the Signing Key button to specify a server certificate. You can select a certificate in the dialog, or click to create or import a certificate. The selected certificate must contain a private key. For more details, see Manage X.509 certificates and keys on page 230. Alternatively, you can specify a certificate to bind to at runtime using an environment variable selector (for example, ${env.serverCertificate}). For details on setting external environment variables for API Gateway instances, see the API Gateway DevOps Deployment Guide.
Server Key Pair:
For SFTP, click the button on the right, and select a previously configured key pair that the file transfer service must present from the tree. To add a key pair, right-click the Key Pairs node, and select Add. Alternatively, you can import key pairs under the Environment Configuration > Certificates and Keys node in the Policy Studio tree. For more details, see Manage X.509 certificates and keys on page 230.
Command settings
For FTP and FTPS, the Commands tab enables you to specify commands that can be enabled for this service (other FTP and FTPS commands are enabled by default). The following commands are specified in the table:
l DELE: Allow user to delete files
l PASV: Support passive mode
l REST: Support restart mode
l RMD: Allow user to remove directories
l STOU: Support unique file name
Axway API Gateway 7.5.2
Policy Developer Guide 350
8 API Gateway instances
To enable an existing command, click Edit, select Enabled, and click OK. The command is displayed as enabled in the table.
Add new commands
To add a new command, perform the following steps:
1. Click the Add button to display the dialog.
2. Enter the command Name (for example, STAT).
3. Select the file transfer protocol Type from the drop-down list (for example, ftp or ftp(s)).
4. Enter the command Description.
5. Select whether the command is Enabled.
6. Click OK to display the new command in the table.
Supported commands
For a full list of supported commands, see http://mina.apache.org/ftpserver-project/ftpserver_
commands.html.
Access control settings
The Access Control tab enables you to restrict or block access to the file transfer service based on IP address. All IP addresses are allowed by default.
Restrict Access to the following IP Ranges:
To restrict access to specified IP addresses, perform the following steps:
1. Click the Add button to display the dialog.
2. Enter an IP Address (for example, 192.168.0.16).
3. Enter a Net Mask for the specified IP address. For example, if you wish to restrict access to the specified IP address only, enter 255.255.255.255. Alternatively, you can restrict access to a range of IP addresses by entering a value such as 255.255.255.253, which restricts access to 192.168.0.16, 192.168.0.17, and 192.168.0.18.
4. Click OK to display the IP address details in the table.
Block Access to the following IP Ranges:
To block access to specified IP addresses, perform the following steps:
1. Click the Add button to display the dialog.
2. Enter an IP Address (for example, 192.168.0.16).
Axway API Gateway 7.5.2
Policy Developer Guide 351
8 API Gateway instances
3. Enter a subnet Mask for the specified IP address. For example, if you wish to block access to the specified IP address only, enter 255.255.255.255. Alternatively, you can block access to a range of IP addresses by entering a value such as 255.255.255.253, which blocks access to 192.168.0.16, 192.168.0.17, and 192.168.0.18.
4. Click OK to display the IP address details in the table.
Message settings
For FTP and FTPS, the you can specify a welcome message and a goodbye message on the Messages tab. These are output to the user at the start and at the end of each session.
Welcome Message:
Enter a short welcome text message for the file transfer service (for example, Connected to
FTP Test Service...).
Goodbye Message:
Enter a short goodbye text message for the file transfer service (for example, Leaving FTP
Test Service...).
Directory settings
You can configure the following settings on the Directory tab:
Directory Type:
Select one of the following directory types:
l Persistent: This is a sharable directory created per user, which persists between connections (for example, ${environment.VINSTDIR}/file-
transfer/in/persistent/fred). This is the default directory type.
l Transient: This is an isolated directory created per connection, which is destroyed after the connection (for example, ${environment.VINSTDIR}/file-
transfer/in/2/fred).
Note
Some clients, notably FileZilla, generate multiple client connection sessions. For these clients, files uploaded in one session are not available in the viewing session.
Directory expiry in seconds:
Specifies how long the directory remains on the system. Defaults to 3600 seconds (1 hour). A setting of 0 seconds means that the directory never expires.
Directory expiry check period in seconds:
Specifies how often the API Gateway checks to see if a directory has expired. Defaults to 1800 seconds (30 minutes). A setting of 0 seconds means that it never checks.
Axway API Gateway 7.5.2
Policy Developer Guide 352
8 API Gateway instances
Logging settings
The Logging Settings tab enables you to configure the logging level for the file transfer service, and to configure when message payloads are logged.
Logging Level
You can configure the following settings on all filters executed on the file transfer service:
Logging
Level
Description
Fatal
Logs Fatal log points that occur on all filters executed. Failure
Logs Failure log points that occur on all filters executed. This is the default logging level.
Success
Logs Success log points that occur on all filters executed. For more details on logging levels, and on how to configure logging for a specific filter, see Set transaction log level and log message on page 758.
Payload Level
You can configure the following settings for the file transfer service payload:
Payload Logging
Description
On receive request
from client
Log the message payload when a request arrives from the client. On send response to
client
Log the message payload before the response is sent back to the client.
On send request to
remote server
Log the message payload before the request is sent using any Connection or Connect to URL filters deployed in policies.
On receive response
from remote server
Log the message payload when the response is received using any Connection or Connect to URL filters deployed in a policies.
For details on how to log message payloads at any point in a specific policy, see Log message payload on page 747.
Include in real time monitoring
Select whether to monitor traffic for the file transfer service. This means that traffic for this service is monitored in the API Gateway Manager and API Gateway Analytics web-based interfaces. For more details, see the API Gateway Administrator Guide. This setting is selected by default. Axway API Gateway 7.5.2
Policy Developer Guide 353
8 API Gateway instances
Traffic monitor settings
The Traffic Monitor tab enables you to configure traffic monitoring settings for the file transfer service. To override the system-level traffic monitoring settings, select Override system-level
settings, and configure the relevant options. For more details, see the API Gateway Administrator Guide.
Configure an FTP poller
Overview
The FTP poller enables you to query and retrieve files to be processed by polling a remote file server. When the files are retrieved, they can be passed to the API Gateway core message pipeline for processing. For example, this is useful where an external application drops files on to a remote file server, which can then be validated, modified, and potentially routed on over HTTP or JMS by the API Gateway. This kind of protocol mediation is useful when integrating with Business-to-Business (B2B) partner destinations or with legacy systems. For example, instead of making drastic changes to either system, the API Gateway can download the files from a remote file server, and route them over HTTP to another back-end system. The added benefit is that messages are exposed to the full complement of API Gateway message processing filters. This ensures that only properly validated messages are routed on to the target system. The FTP poller supports the following file transfer protocols:
l FTP: File Transfer Protocol
l FTPS: FTP over Secure Sockets Layer (SSL)
l SFTP: Secure Shell (SSH) File Transfer Protocol
To add a new FTP poller, in the Policy Studio tree, under the Environment Configuration > Listeners node, right-click the instance name (for example, API Gateway), and select FTP
Poller > Add. This topic describes how to configure the fields on the FTP Poller Settings dialog.
Tip
For details on how to configure the API Gateway to act as a file transfer service that listens on a port for remote clients, see Configure a file transfer service on page 347.
General settings
This filter includes the following general settings:
Name:
Enter a descriptive name for this FTP poller. Axway API Gateway 7.5.2
Policy Developer Guide 354
8 API Gateway instances
Enable Poller:
Select whether this FTP poller is enabled. This is selected by default. Host:
Enter the host name of the file transfer server to connect to. Port:
Enter the port on which to connect to the file transfer server. Defaults to 21.
User name:
Enter the user name to connect to the file transfer server.
Password:
Specify the password for this user.
Scan settings
The fields configured in the Scan details tab determine when to scan, where to scan, and what files to scan:
Poll every (ms):
Specifies how often in milliseconds the API Gateway scans the specified directory for new files. Defaults to 60000. To optimize performance, it is good practice to poll often to prevent the number of files building up. Look in directory on FTP server:
Enter the path of the target directory on the FTP server to scan for new files. For example, outfiles.
For files that match the pattern:
Specifies to scan only for files based on a pattern in a regular expression. For example, to scan only for files with a particular file extension (for example, .xml), enter an appropriate regular expression. Defaults to:
([^\s]+(\.(?i)(xml|xhtml|soap|wsdl|asmx))$)
Establish new session for each file found:
Select whether to establish a new file transfer session for each file found. This is selected by default. Limit the number of files to be processed:
Select this option to limit the number of files that the FTP poller can will process on each poll of the FTP server. This option is not selected by default.
Specify the max number of files to be processed:
Enter the maximum number of files to be processed on each poll of the FTP server. The default is 100.
Process file with following policy:
Click the browse button to select the policy to process each file with. For example, this policy may Axway API Gateway 7.5.2
Policy Developer Guide 355
8 API Gateway instances
perform tasks such as validation, threat detection, content filtering, or routing over HTTP or JMS. You can select what action to take after the policy processes the file in the On Policy Success and On Policy Failure fields. On Policy Success:
This field enables you to choose the behavior if the policy passes. Select one of the following options:
l Do Nothing — Take no action.
l Delete File — Delete the file.
l Move File — Move the file to a new location. Enter the directory path in the Move to directory
on FTP server field. This path is relative to the Look in directory on FTP server entered above. For example, if Look in directory is outfiles and Move to directory is processed, then files are moved to outfiles/processed on the FTP server. The Move
to directory is created if it does not exist.
On Policy Failure:
This field enables you to choose the behavior if the policy fails. Select one of the following options:
l Do Nothing — Take no action.
l Delete File — Delete the file.
l Move File — Move the file to a new location. Enter the directory path in the Move to directory
on FTP server field. This path is relative to the Look in directory on FTP server entered above.
Connection type settings
The fields configured in the Connection Type tab determine the type of file transfer connection. Select the connection type from the list:
l FTP — File Transfer Protocol
l FTPS — FTP over SSL
l SFTP — SSH File Transfer Protocol
FTP and FTPS connections
The following general settings apply to FTP and FTPS connections:
Passive transfer mode:
Select this option to prevent problems caused by opening outgoing ports in the firewall relative to the file transfer server (for example, when using active FTP connections). This is selected by default. File Type:
Select ASCII mode for sending text-based data or Binary mode for sending binary data over the connection. Defaults to ASCII mode.
Axway API Gateway 7.5.2
Policy Developer Guide 356
8 API Gateway instances
FTPS connections
The following security settings apply to FTPS connections only:
SSL Protocol:
Enter the SSL protocol used (for example, SSL or TLS). Defaults to SSL. Implicit:
When this option is selected, security is automatically enabled as soon as the FTP poller client makes a connection to the remote file transfer service. No clear text is passed between the client and server at any time. In this case, the client defines a specific port for the remote file transfer service to use for secure connections ( 990). This option is not selected by default.
Explicit:
When this option is selected, the remote file transfer service must explicitly request security from the FTP poller client, and negotiate the required security. If the file transfer service does not request security, the client can allow the file transfer service to continue insecure or refuse and/or limit the connection. This option is selected by default.
Trusted Certificates:
To connect to a remote file server over SSL, you must trust that server's SSL certificate. When you have imported this certificate into the Certificate Store, you can select it on the Trusted
Certificates tab. Client Certificates:
If the remote file server requires the FTP poller client to present an SSL certificate to it during the SSL handshake for mutual authentication, you must select this certificate from the list on the Client
Certificates tab. This certificate must have a private key associated with it that is also stored in the Certificate Store. SFTP connections
The following security settings apply to SFTP connections only:
Present following key for authentication:
Click the button on the right, and select a previously configured key to be used for authentication from the tree. To add a key, right-click the Key Pairs node, and select Add. Alternatively, you can import key pairs under the Environment Configuration > Certificates and Keys node in the Policy Studio tree. For more details, see Manage X.509 certificates and keys on page 230.
SFTP host must present key with the following finger print:
Enter the fingerprint of the public key that the SFTP host must present (for example, 43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8).
Axway API Gateway 7.5.2
Policy Developer Guide 357
8 API Gateway instances
Configure a directory scanner
Overview
The Directory Scanner enables you to scan a specified directory on the file system for files containing messages (for example, in XML or JSON format). When the messages have been read, they can be passed into the core message pipeline, where the full range of message processing filters can act on them. The Directory Scanner is typically used in cases where an external application is dropping files (perhaps by FTP) on to the file system so that they can be validated, modified, and potentially routed on over HTTP or JMS. Alternatively, they can be stored to another directory where the application can pick them up again. This sort of protocol mediation is very useful in cases where legacy systems are involved. For example, instead of making drastic changes to the legacy system by adding an HTTP engine, the API Gateway can pull the files from the file system, and route them on over HTTP to another back-end system. The added benefit is that messages can be exposed to the full range of message processing filters in the API Gateway. This ensures that only properly validated messages are routed on to the target system. To add a new Directory Scanner, in the Policy Studio tree, under the Environment Configuration > Listeners node, right-click the name of the API Gateway instance (for example, API
Gateway), and select the Directory Scanner > Add menu option. This topic describes how to configure the fields on the Directory Scanner Settings dialog. Input settings
The fields in this section configure where to scan for files, what files to scan, and when to scan.
Input Directory:
Enter or browse to the input directory that the API Gateway scans for files. This setting is required.
Match File:
Select one of the following options to specify how inbound files are filtered:
l By Name:
You can specify a comma-separated list of specific names, wildcarded names, or leave this field blank to accept all files by name. For example, a value of "*.xml,*.xsl" only accepts XML and XSL files in the input directory. l By Extension:
You can specify a comma-separated list of file extensions (excluding the . character), or leave this field blank to accept all files by extension. For example, "xml,xsl" only accepts XML and XSL files in the input directory.
Axway API Gateway 7.5.2
Policy Developer Guide 358
8 API Gateway instances
l By Pattern (regex):
If you wish to scan only for files based on some pattern, you can specify this as a regular expression. For example, if you wish to scan only for files with a particular file extension, such as
.xml , you can enter a regular expression such as the following:
^[a-zA-Z\s]*.xml
Similarly, if a particular naming scheme is used when dropping the files into the configured directory, you can enter a regular expression to scan for these files only. For example, the following regular expression scans only for files named using a yyyy-mm-dd date format:
^(\d{4})[- /.]((1[012])|(0?[1-9]))[- /.]((3[01])|([012]?[1-9])|([12]0))$
Poll Rate (ms):
Specifies the amount of time (in milliseconds) between each scan of the Input Directory for new files. Defaults to 60000.
Processing settings
The fields configured in this section determine what processing is performed on the input files, and where files are placed before and after processing.
Processing Directory:
Enter or browse to the directory to which the input file is copied prior to processing. This field is optional. If it is not specified, the input file is moved to the processing directory specified by the processing policy.
Response Directory:
Enter or browse to the directory to which the response file is copied. This field is optional. If this is not specified, the response file is not written to disk.
Processing Policy:
Select the policy executed on the input file. For example, the policy could perform message validation, routing, virus checking, or XSLT transformation. This setting is required.
File Type:
Specifies how the input file is interpreted. Select one of the following options:
l Raw:
Assumes a content-type of application/octet-stream. This is the default.
l Treat as HTTP Message (including headers):
Assumes the inbound file contains an HTTP request (optionally with HTTP headers).
l Infer content-type from extension:
Performs a lookup on configured MIME types to determine the content-type of the file based on its extension.
l Use Content-type:
Enables you to specify a content-type in the text box. Axway API Gateway 7.5.2
Policy Developer Guide 359
8 API Gateway instances
Sort Files:
Select whether files are sorted, and select one of the following sort types from the list: l Date last modified
l Extension
l Extension (case-sensitive)
l Name
l Name (case-sensitive)
l Size
The default is to sort by Name.
Select one of the following sort directions: l Ascending
l Descending
The default is Ascending.
File Processing:
Select whether to Process files in parallel or Process files in sequence (queued). This option is useful if you need to process very large files, or process files in a particular order (when used in conjunction with the Sort Files option).
On completion settings
You can specify what to do when the file processing has completed. Select one of the following options:
l Do Nothing:
The input file remains in the Input Directory or Processing Directory. This is the default.
l Delete Input File:
The input file is deleted from the Input Directory or Processing Directory. l Move Input File:
The input file is moved (archived) to the directory specified in the To Directory field. You can also specify an optional File Prefix or File Suffix for the archived file.
Traffic monitor settings
The Traffic Monitor tab enables you to configure traffic monitoring settings for the directory scanner. To override the system-level traffic monitoring settings, select Override system-level
settings, and configure the relevant options. For more details, see the API Gateway Administrator Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 360
8 API Gateway instances
Configure a POP client
Overview
The API Gateway POP Client enables you to poll a Post Office Protocol (POP) mail server and read email messages from it. When the messages have been read, they can be passed into the core message pipeline where the full collection of message processing filters can act on them. Configuration
You can configure a POP client by right-clicking an API Gateway instance node under the Environment Configuration > Listeners node in the Policy Studio tree, and selecting the POP
Client > Add menu option. Complete the following fields on the POP Mail Server dialog:
Server Name:
Enter the host name or IP address of the POP mail server.
Port:
Enter the port on which the POP server is listening. By default, POP servers listen on port 110.
Connection Security:
Select the security used to connect to the POP server ( SSL, TLS, or NONE). Defaults to NONE.
User Name:
Enter the user name of a configured mail user for this POP server. Password:
Enter the password for this user.
Poll Rate:
Enter the rate at which the instance polls the mail server in milliseconds.
Delete Message from Server:
Specifies whether the POP server deletes email messages after they have been read by the instance. This setting is selected by default.
Email Debugging:
Select this setting to find out more information about errors encountered by the API Gateway when polling the POP server. All trace files are written to the /trace directory of your API Gateway installation. This setting is not selected by default.
Policy to Use:
Select the policy to use to process messages that have been read from the POP server.
Axway API Gateway 7.5.2
Policy Developer Guide 361
8 API Gateway instances
TIBCO integration
Overview
The API Gateway ships with in-built support for TIBCO Rendezvous. The API Gateway can both produce and consume messages for TIBCO Rendezvous. This topic describes how to integrate TIBCO Rendezvous. TIBCO Rendezvous integration
The API Gateway can act as a producer and a consumer of TIBCO Rendezvous messages. In both cases, a Rendezvous daemon must be configured. This is responsible for communicating with other Rendezvous programs on the network.
Producing TIBCO Rendezvous Messages:
You must perform the following steps to produce messages and send them to another Rendezvous program:
l Configure TIBCO Rendezvous daemons on page 427
l Route to TIBCO Rendezvous on page 801
Consuming TIBCO Rendezvous Messages:
A TIBCO Rendezvous Listener can be configured at the API Gateway instance level to consume Rendezvous messages. You must perform the following steps to consume Rendezvous messages:
l Configure TIBCO Rendezvous daemons on page 427
l TIBCO Rendezvous listener on page 362
TIBCO Rendezvous listener
Overview
TIBCO Rendezvous is a low latency messaging product for real-time high throughput data distribution applications. A message can be sent from the TIBCO daemon running on the local machine to a single TIBCO daemon running on a separate host machine or it can be broadcast to several daemons running on multiple machines. Each message has a subject associated with it, which acts as the destination of the message. A listener, which is itself a TIBCO daemon, can declare an interest in a subject on a specific daemon. Whenever a message is delivered to this subject on the daemon, the message is delivered to the listening daemon. Axway API Gateway 7.5.2
Policy Developer Guide 362
8 API Gateway instances
The API Gateway can act as a listener on a specific subject at a TIBCO daemon, in which case it said to be acting as a consumer of TIBCO messages. Similarly, it can also send messages to a TIBCO daemon, effectively acting as a producer of messages. For more information on how to send messages to other TIBCO Rendezvous programs, see Route to TIBCO Rendezvous on page 801.
Configuration
You can configure a TIBCO Rendezvous Listener at the API Gateway instance level in the Policy Studio. To add a listener, perform the following steps: 1. In the Policy Studio tree, expand the Environment Configuration > Listeners node.
2. Right-click the API Gateway instance, and select TIBCO > Rendezvous Listener > Add.
3. Configure the following fields on the TIBCO Rendezvous Listener dialog:
l TIBCO Settings tab:
Enter the name of the subject that you want this consumer to listen for in the Rendezvous Subject field. Only messages addressed with this subject are consumed by the listener.
Click the button next to the TIBCO Rendezvous Daemon to use field, and select a previously configured TIBCO Rendezvous Daemon to communicate with other TIBCO programs. To add a TIBCO Rendezvous Daemon, right-click the TIBCO Rendezvous
Daemons tree node, and select Add a TIBCO Rendezvous Daemon. For more details, see Configure TIBCO Rendezvous daemons on page 427.
l Policy to Use:
When messages with the specified subject have been consumed they must be passed into a policy where they can be processed accordingly. Select the policy that you want to use to process consumed messages from the tree. Configure Amazon SQS queue listener
Overview
Amazon Simple Queue Service (SQS) is a hosted message queuing service for distributing messages amongst machines. You can configure API Gateway to poll an Amazon SQS queue at a set rate. Any message found on the SQS queue in this interval can be sent to a policy for processing. For more information on Amazon SQS, go to http://aws.amazon.com/sqs/. To add a new Amazon SQS queue listener, in the Policy Studio tree, under the Environment
Configuration > Listeners node, right-click the instance name (for example, API Gateway), and select Amazon Web Services > Add SQS Queue Listener.
Axway API Gateway 7.5.2
Policy Developer Guide 363
8 API Gateway instances
General settings
You can configure the following general settings for the Amazon SQS queue listener:
Name:
Enter a suitable name for this SQS listener. AWS settings
AWS Credential:
Click the browse button to select your AWS security credentials (API key and secret) to be used by API Gateway when connecting to Amazon SQS.
Region:
Select the region appropriate for your deployment. You can choose from the following options:
l US East (Northern Virginia)
l US West (Oregon)
l US West (Northern California)
l EU (Ireland)
l Asia Pacific (Singapore)
l Asia Pacific (Tokyo)
l Asia Pacific (Sydney)
l South America (Sao Paulo)
l US GovCloud
Client settings:
Click the browse button to select the AWS client configuration to be used by API Gateway when connecting to Amazon SQS. For more details, see Configure AWS client settings on page 365.
Poll settings
Poll the queue <queueName> every <pollRate> milliseconds:
Enter the name of the queue to be polled and the rate at which the queue is to be polled, in milliseconds. The default queue name is requestQueue and the default poll rate is 10000 milliseconds (10 seconds).
Call policy:
Click the browse button to select a policy to send the message to for processing. When a message has been consumed from the queue it is passed to the selected policy for processing. Process the retrieved messages as body with following Content Type:
Select this option to create a body from the message, and enter a content type. The default is text/xml.
Axway API Gateway 7.5.2
Policy Developer Guide 364
8 API Gateway instances
Store the content of the retrieved messages in the following attribute:
Select this option to store the content of the message in an attribute, and enter the attribute name. The default attribute name is sqs.body.
Delete message on completion:
Select this option to delete the message from the queue when processing is complete. This is selected by default.
Maximum number of messages to read from queue:
Enter the maximum number of messages to return. Amazon SQS never returns more messages than this value but it might return less. The default value is 10.
Visibility timeout for other consumers:
Enter the duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by API Gateway. The default value is 1000 seconds.
Response settings
Write a response message:
Select this option to write the contents of an attribute to a response queue. This is not selected by default.
Response queue name:
If you selected the Write a response message option, enter the name of the response queue in this field. The default name is responseQueue.
Use content body as the response:
Select this option to use the content body as the response.
Use the following attribute as the response:
Select this option to use an attribute as the response, and enter an attribute selector for the attribute containing the response in this field (for example, ${sqs.body}). For more details on selectors, see Select configuration values at runtime on page 854.
Configure AWS client settings
API Gateway is a client of AWS, and as such you can define a client profile by which API Gateway connects to AWS. When you click the browse button on the Client settings field for an Amazon SQS queue listener, a Send to Amazon SQS filter, an Upload to Amazon S3 filter, or an Amazon Simple Notification Service (SNS) alert destination, you can edit the configuration of the AWS client profile.
To edit the configuration, right-click the Default AWS Client Configuration and select Edit. Configure the following settings on the dialog:
Name:
Enter a suitable name for this client configuration. Axway API Gateway 7.5.2
Policy Developer Guide 365
8 API Gateway instances
Connection settings
Maximum number of open HTTP connections:
Enter the maximum number of open HTTP connections. The default value is 50.
Socket timeout:
Enter the amount of time to wait (in milliseconds) for data to be transferred over an established, open connection before the connection is timed out. The default value is 50000 milliseconds. A value of 0 means infinity, and is not recommended. Connection timeout:
Enter the amount of time to wait (in milliseconds) when initially establishing a connection before giving up and timing out. The default value is 50000 milliseconds. A value of 0 means infinity, and is not recommended.
Maximum number of retries:
Enter the maximum number of retry attempts for failed requests (that can be retried). The default value is 3. User agent:
Enter the HTTP user agent header to send with all requests.
Protocol:
Select the protocol (HTTP or HTTPS) to use when connecting to AWS.
Proxy settings
You can optionally configure the following proxy settings:
Proxy Host:
Enter the proxy host to connect through.
Proxy port:
Enter the port on the proxy host to connect through. User name:
Enter the user name to use when connecting through a proxy.
Password:
Enter the password to use when connecting through a proxy. NTLM Proxy support:
To configure Windows NT LAN Manager (NTLM) proxy support, enter the Windows domain name in the Windows domain field and enter the Windows workstation name in the Windows
workstation name field.
Axway API Gateway 7.5.2
Policy Developer Guide 366
8 API Gateway instances
Advanced settings
You can optionally configure these settings to tune low level TCP parameters to try and improve performance.
Note
These settings are for advanced users only.
Size hint (in bytes) for the low level TCP send buffer:
Enter the size hint (in bytes) for the low level TCP send buffer.
Size hint (in bytes) for the low level TCP receive buffer:
Enter the size hint (in bytes) for the low level TCP receive buffer. Further information
For more detailed information on Amazon Web Services integration, see the AWS Integration Guide available from Axway Support.
Cryptographic acceleration
Overview
The API Gateway uses OpenSSL to perform cryptographic operations, such as encryption and decryption, signature generation and validation, and SSL tunneling. OpenSSL exposes an Engine API, which makes it possible to plug in alternative implementations of some or all of the cryptographic operations implemented by OpenSSL. When configured appropriately, OpenSSL calls the engine's implementation of these operations instead of its own.
For example, a particular engine might provide improved implementations of the asymmetric operations RSA and DSA. This engine can then be plugged into OpenSSL so that whenever OpenSSL needs to perform either an RSA or DSA operation, it calls out to the engine's implementation of these algorithms rather than call its own.
Typically, OpenSSL engines provide a hardware implementation of specific cryptographic operations. The hardware implementation usually offers improved performance over its softwarebased counterpart, which is known as cryptographic acceleration.
You can configure cryptographic acceleration at the instance level in the API Gateway. To configure the API Gateway instance to use an OpenSSL engine instead of the default OpenSSL implementation, perform the following steps:
1. In the Policy Studio tree, expand Environment Configuration > Listeners.
2. Right-click the API Gateway instance, and select Cryptographic Acceleration > Add
OpenSSL Engine.
Axway API Gateway 7.5.2
Policy Developer Guide 367
8 API Gateway instances
General configuration
The OpenSSL Engine Configuration dialog displays the name of the engine, the algorithms that it implements, together with any initialization and cleanup commands required by the engine. Complete the following fields:
Name:
Enter an appropriate name for the engine in this field.
Provides:
Enter a comma-separated list of cryptographic operations to be performed by the engine instead of OpenSSL. The engine must implement the listed operations, otherwise the default OpenSSL operations are used. The following operations are available:
RSA
RSA (Rivest Shamir Adleman) asymmetric algorithm
DSA
DSA (Digital Signature Algorithm) asymmetric algorithm
RAND
Random number generation
DH
Diffie-Hellman anonymous key exchange algorithm
ALL
Engine's implementation of all cryptographic algorithms
For example, to configure the API Gateway to use the engine's implementation of the RSA, DSA, and DH algorithms only, enter the following in the Provides field:
RSA, DSA, DH
Commands:
The OpenSSL engine framework allows a number of control commands to be invoked at various stages in the loading and unloading of a specific engine library. These commands can be issued before or after the initialization of the engine, and also before or after the engine is uninitialized. Control commands are based on text name-value pairs.
Typical uses for control commands include specifying the path to a driver library, logging configuration information, a password to access protected devices, a configuration file required by the engine, and so on.
OpenSSL control commands can be added by clicking the Add button. Enter the name of the command in the Name field, and its value in the Value field. This command must b e supported by the engine.
Use the When drop-down list to select when the command is to be run. The options available are as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 368
8 API Gateway instances
preInit
Command is run before the engine is initialized (before the call to ENGINE_init()).
postInit
Command is run after the engine is initialized (after the call to ENGINE_
init()).
preShutdown
Command is run before the engine shuts down (before the call to ENGINE_finish()).
postShutdown
Command is run after the engine shuts down (after the call to ENGINE_
finish()).
Conversations for crypto engines
A Hardware Security Module (HSM) protects the private keys that it holds using a variety of mechanisms, including physical tokens, passphrases, and other methods. When use of the private key is required by an agent, it must authenticate itself with the HSM, and be authorized to access this data.
For information on how the API Gateway interacts with the HSM, see Cryptographic acceleration conversation: request-response on page 369. For more information on storing private keys on OpenSSL engines, see Manage X.509 certificates and keys on page 230.
Cryptographic acceleration conversation:
request-response
Conversations for crypto engines
Hardware Security Modules (HSM) protect the private keys they hold using a variety of mechanisms, including physical tokens, passphrases, and other methods. When use of the private key is required by some agent, it must authenticate itself with the HSM, and be authorized to access this data.
Whatever the mechanism protecting the keys on the HSM, this commonly requires some interaction with the agent. The most common form of interaction required is for the agent to present a passphrase. The intent is generally that this is carried out by a real person, rather than produced mechanically by the agent. Other forms of interaction may include prompting the operator to insert a specific card into a card reader.
However, the requirement for an operator to enter a passphrase renders automated startup of services using the HSM impossible. Although weaker from a security standpoint, the server can Axway API Gateway 7.5.2
Policy Developer Guide 369
8 API Gateway instances
conduct an automated dialog with a HSM when it requires access to a private key, presenting specific responses to specific requests, including feeding passphrases to it. Of course, this is futile if the dialog calls for the insertion of a physical token in a device.
The dialog for different keys on the same device is often the same. For example, a number of keys on a Thales nShield Solo HSM (provided locally with the API Gateway Appliance), may require the server to present an operator passphrase for a preinserted card in a card-reader. The specific dialogs are therefore associated with the cryptographic engine.
Each dialog consists of a set of expected request-generated response pairs. The expected request takes the form of a regular expression. When the cryptographic device prompts for input, the text of this prompt is compared against each expected request in the conversation, until a match is found. When matched, the corresponding generated response is delivered to the HSM.
In the simplest case, consider a HSM producing the following prompt:
Enter passphrase for operator card Operator1:
You can identify this, for example, with the following regular expression:
"passphrase.*Operator1"
In the configured conversation, you can make the expected response to this prompt the passphrase for the specific card, for example:
"tellNoOne"
The server is somewhat at the mercy of the HSM for how this dialog continues. If the HSM continues to prompt for requests, the server can only attempt to respond. You may set the maximum expected challenge setting on the conversation to indicate a maximum number of prompts to expect from the HSM, at which point the server does its best to terminate the conversation, almost certainly failing to load the affected key.
Axway API Gateway 7.5.2
Policy Developer Guide 370
External connections
9
This section describes how to configure external connections.
External connections
371
Configure authentication repositories
377
Configure Axway PassPort authentication repositories
391
Configure client credentials
395
Configure database connections
399
Configure database queries
402
Configure ICAP servers
404
Configure Sentinel servers
406
Configure Kerberos clients
407
Configure Kerberos principals
412
Configure Kerberos services
414
Kerberos keytab concepts
417
Configure LDAP directories
418
Configure proxy servers
421
Configure RADIUS clients
422
Configure SiteMinder/SOA Security Manager connections
423
Configure SMTP servers
426
Configure TIBCO Rendezvous daemons
427
Configure Tivoli connections
429
Configure XKMS connections
430
External connections
API Gateway can leverage your existing Identity Management infrastructure, thus avoiding the need to maintain separate silos of user information. For example, if you already have a database full of user credentials, API Gateway can authenticate requests against this database, rather than using its own internal user store. Similarly, API Gateway can authorize users, look up user attributes, and validate certificates against third-party Identity Management servers.
You can add a connection to an external system as a global external connection in Policy Studio so that it can be reused across all filters and policies. For example, if you create a policy that authenticates users against an LDAP directory, and then validates an XML signature by retrieving a public key from the same LDAP directory, it makes sense to create a global external connection for that LDAP directory. You can then select the LDAP connection in both the authentication and XML signature verification filters, rather than having to reconfigure them in both filters.
Axway API Gateway 7.5.2
Policy Developer Guide 371
9 External connections
You can also use external connections to configure a group of related URLs. This allows you to round-robin between a number of related URLs to ensure high availability. When API Gateway is configured to use a URL connection set (instead of a single URL), it round-robins between the URLs in the set.
To configure external connections, right-click the appropriate node in Policy Studio tree (for example, Environment Configuration > External Connections > Database Connections). This topic introduces the different types of external connection and shows where to obtain more details.
Authentication repository profiles
API Gateway can authenticate users against external databases and LDAP repositories, in addition to its own local user store. You can also use a number of bespoke authentication connectors to enable API Gateway to authenticate against specific third-party Identity Management products.
Connection details for these authentication repositories are configured at a global level, making them available for use across authentication (and authorization) filters. This saves the administrator from reconfiguring connection details in each filter.
For example, the available authentication repository types include the following:
l CA SiteMinder Repositories
l Database Repositories
l Entrust GetAccess Repositories
l LDAP Repositories
l Local Repositories (for example, Local User Store)
l Oracle Access Manager Repositories
l Oracle Entitlements Server Repositories
l RADIUS Repositories
l RSA Access Manager Repositories
l Tivoli Repositories
l Sun Access Manager Repositories
For details on how to configure the various authentication repository types, see Configure authentication repositories on page 377.
Connection sets
Connection sets are used by API Gateway to round-robin between groups of external servers (for example, RSA Access Manager). You can reuse these global groups when configuring connections to external servers in Policy Studio. For this reason, connection sets are available under the External Connections node according to the filter from which they are available. For example, connection sets under the RSA ClearTrust Connection Sets node are available in the RSA
Access Manager filter.
Axway API Gateway 7.5.2
Policy Developer Guide 372
9 External connections
At runtime, API Gateway can round-robin between the servers in the group to ensure that if one of the servers becomes unavailable, API Gateway can use one of the other servers in the group.
To add a connection set for a particular category of filters, right-click the appropriate node under the Connection Sets node under the External Connections node. Select Add a Connection
Set to display the Connection Group dialog. For more details, see Configure connection groups on page 866.
Client credentials
Client credentials allow you to configure client authentication settings at a global level. You can configure a client credential profile for the following authentication options: l API keys as a client
l HTTP basic
l Kerberos
l OAuth 2.0 as a client
After configuring a client credential profile globally, you can select that profile for use at the filter level (for example, in the Connection or Connect To URL filters).
To add a client credential profile for a particular authentication mechanism, right-click the appropriate node under the Client Credentials node under the External Connections node. For more details, see Configure client credentials on page 395.
Database connections
API Gateway typically connects to databases to authenticate or authorize users using API Gateway's numerous Authentication and Authorization filters. Similarly, API Gateway can retrieve user attributes from a database (for example, which can then be used to generate SAML attribute assertions later in the policy).
You can configure database connections globally under the External Connections node, making them available to the various filters that require a database connection. This means that an administrator can reuse the same database connection details across multiple authentication, authorization, and attribute-based filters.
API Gateway maintains a JDBC pool of database connections to avoid the overhead of setting up and tearing down connections to service simultaneous requests. This pool is implemented using Jakarta DBCP (Database Connection Pools) . The settings in the Advanced section of the Configure Database Connection dialog are used internally by API Gateway to initialize the connection pool. The table at the end of this section shows how the fields correspond to specific configuration DBCP settings.
To configure details for a global database connection, right-click the External Connections >
Database Connections node. Select the Add a Database Connection menu option, and configure the fields on the Configure Database Connection dialog. For details on configuring these fields, see Configure database connections on page 399.
Axway API Gateway 7.5.2
Policy Developer Guide 373
9 External connections
ICAP servers
The Internet Content Adaptation Protocol (ICAP) is a lightweight HTTP-based protocol used to optimize proxy servers, which frees up resources and standardizes how features are implemented. For example, ICAP is typically used to implement features such as virus scanning, content filtering, ad insertion, or language translation in the HTTP proxy cache.
When an ICAP Server is configured under the External Connections node, you can then select it in multiple ICAP filters. For details on how to configure an ICAP server, see Configure ICAP servers on page 404.
Sentinel servers
You can send events from API Gateway to Axway Sentinel. When a Sentinel server is configured under the External Connections node, you can then select it in multiple Sentinel monitoring filters. For details on how to configure a Sentinel server, see Configure Sentinel servers on page 406.
JMS services
The Java Message Service (JMS) is a Java message-oriented middleware API for sending messages between two or more clients. When a JMS Service is configured under the External Connections node, it is available for selection in multiple JMS-related configuration screens. This enables you to share JMS configuration across multiple filters.
For more details on configuring JMS services, see Configure messaging services on page 161.
Kerberos connections
You can configure global Kerberos Clients, Kerberos Services, and Kerberos Principals under the External Connections node. When a Kerberos item is configured, it is available for selection in all Kerberos-related configuration screens that require this item. This enables you to share Kerberos configuration items across multiple filters.
For more details, see the following topics:
l Configure Kerberos clients on page 407
l Configure Kerberos services on page 414
l Configure Kerberos principals on page 412
See also the API Gateway Kerberos Integration Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 374
9 External connections
LDAP connections
In the same way that database connections can be configured globally in Policy Studio (and then reused across individual filters), LDAP connections are also managed globally in Policy Studio. LDAP connections are used by authentication, authorization, and attribute filters. Filters that require a public key (from a public-private key pair) can also retrieve the key from an LDAP source.
When a filter that uses an LDAP directory is run for the first time, it binds to the LDAP directory using the connection details configured on the Configure LDAP Server dialog. Usually the connection details include the user name and password of an administrator user who has read access to all users in the LDAP directory for whom you wish to retrieve attributes or authenticate.
For details on how to configure a global LDAP connection, see Configure LDAP directories on page 418.
Proxy servers
You can configure proxy servers under the External Connections node, which can then be specified in the Connection and Connect To URL filters. When configured, the filter connects to the proxy server, which routes the message to the destination server.
To configure a proxy server, click the External Connections node, and select Proxy Servers >
Add a Proxy Server. For details on how to configure the settings the Proxy Server Settings dialog, see Configure proxy servers on page 421.
RADIUS clients
The Remote Authentication Dial In User Service (RADIUS) protocol provides centralized authentication and authorization for clients connecting to remote services.
To configure a client connection to a remote server over the RADIUS protocol, click the External
Connections node, and select RADIUS Clients > Add a RADIUS Client. For details on how to configure the settings the RADIUS Client dialog, see the Configure RADIUS clients on page 422.
For details on how to configure a RADIUS Authentication Repository, see Configure authentication repositories on page 377.
SiteMinder and SOA Security Manager
To add a CA SiteMinder or CA SOA Security Manager connection, right-click the SiteMinder/SOA
Security Manager node under the External Connections node, and select Add a SiteMinder
Connection to display the SiteMinder Connection Details dialog. For details on configuring the fields on this dialog, see Configure SiteMinder/SOA Security Manager connections on page 423.
Axway API Gateway 7.5.2
Policy Developer Guide 375
9 External connections
SMTP servers
You can configure a Simple Mail Transfer Protocol (SMTP) server as a global configuration item under the External Connections node. The SMTP filter in the Routing category can then reference this SMTP server. To configure an SMTP server, right-click the External Connections >
SMTP Servers node, and select Add an SMTP Server. For more details, see Configure SMTP servers on page 426.
Syslog servers
You can configure syslog servers globally, and then select them as a customized logging destination for an API Gateway instance. Right-click the External Connections > Syslog Servers node, and select Add a Syslog Server. Complete the following fields on the Syslog Server dialog:
Name:
Enter an appropriate name for the syslog server.
Host:
Enter the host and UDP port on which the syslog daemon is running. Enter in the format of HOST_
OR_IP_ADDRESS:UDP_PORT (for example, 192.0.2.0:514). Alternatively, you can enter HOST_OR_IP_ADDRESS only, and the default port of 514 is used.
Facility:
Select the syslog facility to log to (for example, local0).
Note
For details on how to configure the API Gateway instance to enable logging to this remote syslog server, see the API Gateway Administrator Guide.
TIBCO
You can add a connection to TIBCO Rendezvous daemon. To add a connection, right-click the External Connections > TIBCO Rendezvous Daemon node in the tree, and select Add a
TIBCO Rendezvous Daemon. For details on configuring the fields on the dialog, see Configure TIBCO Rendezvous daemons on page 427.
Tivoli
You can create a connection to an IBM Tivoli server to enable integration between the API Gateway and Tivoli Access Manager for e-business 6.1. Tivoli connections can then be used by API Gateway's Tivoli filter to delegate authentication and authorization decisions to Tivoli Access Manager, and to leverage existing Tivoli Access Manager policies.
To add a Tivoli connection, right-click the External Connections > Tivoli Connections node in the tree, and select Add a Tivoli Connection. For more details on configuring the fields on the Tivoli Configuration dialog, see Configure Tivoli connections on page 429.
Axway API Gateway 7.5.2
Policy Developer Guide 376
9 External connections
URL connection sets
URL connection sets are used by API Gateway filters to round-robin between groups of external servers (for example, Entrust GetAccess, SAML PDP, or XKMS). These global groups can then be reused when configuring these filters in Policy Studio. For this reason, URL connection sets are available under the External Connections node in the tree, according to the filters from which they are available. For example, URL sets under the XKMS URL Sets node are only available from the XKMS Certificate Validation filter.
At runtime, API Gateway can round-robin between the servers in the group to ensure that if one of the servers becomes unavailable, API Gateway can use one of the other servers in the group.
To add a URL connection set for a particular category of filters, right-click the appropriate node under the External Connections > URL Connection Sets node in the tree. Select the Add a
URL Set option to display the URL Group dialog. For more details, see Configure URL groups on page 876.
XKMS connections
API Gateway can also validate certificates against an XKMS (XML Key Management Service) responder or group of responders. An XKMS consists of a group of XKMS responders to validate certificates against, coupled with the signing key to use for signing requests to each of the responders in the group.
To add a global XKMS connection, right-click the External Connections > XKMS Connection node in the tree, and select the Add an XKMS Connection option to display the Certificate
Validation - XKMS dialog. For more details, see Configure XKMS connections on page 430.
All global XKMS Connections are available for selection when configuring the Certificate
Validation - XKMS filter. This saves the administrator from reconfiguring XKMS connection details across multiple filters.
Configure authentication repositories
API Gateway supports a wide range of common authentication schemes, including SSL, XML signatures, WS-Security Username tokens, and HTTP authentication. With SSL, the client authenticates to API Gateway using a client certificate. With XML signatures, the client is authenticated by validating the signature contained within the XML message. However, when API Gateway attempts to authenticate a client using a user name and password (for example, WSSecurity Username tokens or HTTP authentication), it must compare the user name and password presented by the client to those stored in the authentication repository.
The authentication repository acts as a repository for users. Users serve many roles in API Gateway. For example, clients whose user name and password combinations are stored in the authentication repository can authenticate to API Gateway using that user name and password combination. For more information on users, see Manage API Gateway users on page 243.
Axway API Gateway 7.5.2
Policy Developer Guide 377
9 External connections
The authentication repository can be maintained in API Gateway's local configuration store, in an LDAP directory, or in a range of third-party Identity Management products and services. When a user has been successfully authenticated against one of these repositories, API Gateway can use any one of that user's stored attributes (for example, distinguished name (DName), email address, user name) to authorize that same user in a subsequent authorization filter.
For example, this credential mapping is useful in cases where your client-base uses user name and password combinations for authentication ( authentication attributes), but their access rights must be looked up in an authorization server using the client's DName ( authorization attribute). In this way, the client possesses a single virtual identity within API Gateway. The client can use one identity for authentication, and another for authorization, yet API Gateway sees both identities as representing the same client.
You can add a new repository under the Environment Configuration > External Connections node in Policy Studio node tree. Right-click the appropriate node (for example, Database
Repositories), and select Add a new Repository. Similarly, you can edit an existing repository. Right-click the repository node (for example, the default Local User Store), and select Edit
Repository. You can reuse the repositories added under the External Connections node in multiple filters.
Axway PassPort repositories
API Gateway can integrate with Axway PassPort to authenticate and authorize users for resources. To authenticate users against an Axway PassPort repository, right-click Axway PassPort
Repositories, and select Add a new Repository. For more details on configuring a connection to an Axway PassPort repository, see Configure Axway PassPort authentication repositories on page 391. For details on integrating with Axway PassPort using an authorization filter, see Axway PassPort authorization on page 534.
CA SiteMinder repositories
If the user profiles are stored in an existing CA SiteMinder server, API Gateway can query SiteMinder to authenticate users.
To authenticate users against a SiteMinder repository, right-click CA SiteMinder Repositories, and select Add a new Repository. Complete the following fields on the Authentication Repository dialog:
Repository Name:
Enter a suitable name for this repository.
Agent Name:
Select a previously configured SiteMinder agent name from the list. To register a new agent, see API Gateway Authentication and Authorization Integration Guide.
Resource:
Enter the name of the protected resource for which the user must be authenticated. Alternatively, you can enter a selector for a message attribute, which is looked up and expanded to a value at runtime. Message attribute selectors have the following format:
Axway API Gateway 7.5.2
Policy Developer Guide 378
9 External connections
${message.attribute}
For example, by default API Gateway specifies the original path the end user requested as the resource:
${http.request.uri}
Action:
The user must be authenticated for a specific action on the protected resource. By default, API Gateway takes this action from the HTTP verb used in the incoming request. You can use the following selector to get the HTTP verb:
${http.request.verb}
Alternatively, you can enter any user-specified value. For more details on selectors, see Select configuration values at runtime on page 854.
Single Sign-On Token:
By default, when an end user has been authenticated for a given resource, SiteMinder generates a single sign-on token (a session cookie). API Gateway stores this cookie in a user-specified message attribute. API Gateway returns the cookie to the end user along with the response. The end user can then pass this cookie with future requests to API Gateway. When API Gateway receives such a request, it can validate the session cookie using the CA SiteMinder Session Validation filter. The client stays authenticated for the entire lifetime of the session cookie. As long as the session cookie is valid, API Gateway does not need to re-authenticate the end user against SiteMinder for every request. This increases throughput and performance considerably.
Put Token in Message Attribute:
Enter the name of the message attribute where you wish to store the session cookie. By default, the cookie is stored in the siteminder.session attribute.
For more details how to integrate API Gateway with SiteMinder, see API Gateway Authentication and Authorization Integration Guide.
Database repositories
API Gateway can store its authentication repository in an external database. This option makes sense if your organization already has a silo of user profiles stored in the database and you do not want to duplicate this store within API Gateway's local configuration storage.
To authenticate users against a database repository, right-click Database Repositories, and select Add a new Repository. Complete the following fields on the Authentication Repository dialog:
Repository Name:
Enter an appropriate name for the database in the Repository Name field.
Database:
There are two basic configuration items required to retrieve a user's profile from the database:
Axway API Gateway 7.5.2
Policy Developer Guide 379
9 External connections
l Database Location:
To configure connection details for the database, click Add, and complete the Database Connection dialog. For details on configuring the fields on this dialog, see Configure database connections on page 399. To edit or remove previously configured database connections, select them from the drop-down list and click Edit or Delete.
l Database Query:
Database Query retrieves the profile of a specific user from the database to enable API Gateway to authenticate the user. after a successfull authentication, you can select an attribute of this user to use for the authorization filter later in the policy. Database Query can be an SQL statement, stored procedure, or function call. For details on how to configure Database
Query, see Configure database queries on page 402.
Format Password Received From Client:
If the user sends up a clear-text password to API Gateway, but that user's password is stored in a hashed format in the database, API Gateway must hash the password before performing the authentication step.
l Hash Client Password:
Depending on whether you wish to hash the user's submitted password, select the appropriate option.
l Hash Format:
If you have selected to hash the client's password, you must specify the format of the hashed password. The most typical formats have been listed, but you can also enter another format. Formats should be entered in terms of message attribute selectors. The following formats are available from the Hash Format list.
${authentication.subject.id}:${authentication.subject.realm}:${authentication.sub
ject.password}
${authentication.subject.password}
The first option combines the username, authentication realm, and password respectively. This combination is then hashed. The second option simply creates a hash of the user's password.
l Hash Algorithm:
Select either MD5 or SHA1 as the digest algorithm to use when creating the hash.
For more details on selectors, see Select configuration values at runtime on page 854.
Query Result Processing:
You can use these options to provide API Gateway with some meta information about the result Database Query returns. You can identify the name of the database table column or row that contains the user's password, as well as the name of the column or row that contains the attribute that is to be used for the authorization filter.
l Password Column:
Specify the name of the database table column that contains the user's password. The contents of this column are compared to the password the user submits.
l Password Type:
Depending on how the user's password has been stored in the database, select either Clear
Password or Digest Password.
Axway API Gateway 7.5.2
Policy Developer Guide 380
9 External connections
l Authorization Attribute Column:
When Database Query is run, all of the user's attributes are returned. Only the user's user name and password are used for the authentication event. In addition, you can use one of the other user's attributes for authorization at a later stage in the policy. The additional authorization attribute must be either a user name or an X.509 DName. Enter the name of the column containing the user name or the DName here, but only if this value is required for authorization purposes.
l Authorization Attribute Format:
API Gateway's authorization filters are all based on a user name or DName. All authorization filters evaluate if a user identified by a user name or DName is allowed to access a specific resource. Select the appropriate format from the drop-down list depending on what type of user credential is stored in the database table column entered above.
Entrust GetAccess repositories
Entrust GetAccess provides Identity Management and access control services for web resources. It centrally manages access to Web applications, enabling users to benefit from a single sign-on capability when accessing the applications that they are authorized to use.
You can configure API Gateway to connect to a group of GetAccess servers in a round-robin fashion. This provides the necessary failover capability if one or more GetAccess servers are not available. When API Gateway successfully authenticates to a GetAccess server, it obtains authorization information about the end user from the GetAccess SAML PDP. The authorization details are returned in a SAML authorization assertion thatAPI Gateway then validates to determine whether the request should be allowed.
To authenticate users against an Entrust GetAccess repository, right-click Entrust GetAccess
Repositories, and select Add a new Repository. Configure the following fields on the Authentication Repository dialog:
Repository Name:
Enter an appropriate name for this repository.
Request:
Configure the following request settings:
l URL Group:
Select a URL group from the drop-down list. This group consists of a number of GetAccess Servers to which API Gateway round-robins connection attempts. To add URL groups, in the node tree, click Environment Configuration > External Connections > URL
Connection Sets, right-click Entrust GetAccess URL Sets, and select Add a URL Set. For more details on adding and editing URL groups, see Configure URL groups on page 876.
l WS-Trust Attribute Field Name:
Specify the field name for the Id field in the WS-Trust request. The default is Id.
Response:
Configure the following response settings:
l SOAP Actor/Role:
To add the SAML authorization assertion to the response message, select a SOAP actor/role to Axway API Gateway 7.5.2
Policy Developer Guide 381
9 External connections
indicate the WS-Security block where the assertion is added. If you leave this field blank, the assertion is not added to the message.
l Drift Time:
The specified time is used to allow for the possible difference between the time on the GetAccess SAML PDP and the time on the machine hosting API Gateway. This comes into effect when validating the SAML authorization assertion.
For details on using a filter to integrate API Gateway with Entrust GetAccess, see Entrust GetAccess authorization on page 538.
Local repositories
The Authentication Repository can be maintained in the same database that API Gateway uses to store all its configuration information. To edit the default user store, select Local Repositories >
Local User Store > Edit Repository. Alternatively, to create a new user store, select Local
Repositories > Add a new Repository.
You can enter an appropriate name for the repository in the Repository Name field. The Authorization Attribute Format field enables administrators to specify whether to use the client's X.509 Distinguished Name or User Name in subsequent authorization filters. If User
Name is selected, the user name the client uses to authenticate to API Gateway is used in any configured authorization filters. If X.509 Distinguished Name is selected, the X.509 DName API Gateway has stored for that user is used for subsequent authorization.
For example, if the administrator selects User Name from the Authorization Attribute Format list, admin (the User Name field) is used for authorization. Alternatively, if the administrator selects X.509 Distinguished Name, the X.509 DName is used for authorization (for example, O=Company, OU=comp, [email protected], CN=emp).
For more information on adding and configuring users to the authentication repository, see Manage API Gateway users on page 243.
LDAP repositories
In cases where an organization stores user profiles in an LDAP directory, it does not make sense to re-enter these profiles into the default API Gateway user store. Instead, API Gateway can leverage an existing LDAP directory by querying it for user profile data. If a user's profile can be retrieved, and you can bind to the LDAP directory as that user, the user is authenticated.
Authentication with LDAP
When a filter is configured to authenticate a user against an LDAP repository using a user name and password combination, the flow is as follows:
Axway API Gateway 7.5.2
Policy Developer Guide 382
9 External connections
1. A pooled LDAP connection to the repository selected in the LDAP Directory field is retrieved.
2. A search filter is run using the retrieved connection (for example, (&(objectClass=
{User})(sAMAccountName={c05vc}))). Attributes configured in the Login
Authentication Attribute and Authorization Attribute fields are retrieved in this search.
For example, if you select Distinguished Name from the drop-down list, the user's DName is retrieved from the LDAP directory. This uniquely identifies the user in the LDAP directory, and is used to bind to the directory so the user's password can be verified. The attribute specified in Login Authentication Attribute is used when you bind as any user. The value of the attribute specified in Authorization Attribute is stored in authentication.subject.id, and can be used by subsequent filters in the policy (for example, Authorization filters that authorize the authenticated user).
3. If no results are returned from the search, the user is not found in the directory. It is important that the administrator user configured on the Configure LDAP Server window has the ability to see the user that you are attempting to authenticate.
4. If multiple users are returned from the search, an attempt is made to bind to the directory using each Login Authentication Attribute value retrieved from the search, together with the password from the message.
5. If more than one user is authenticated correctly, an error is returned because you only want to authenticate a single user.
6. If no user is authenticated, an error is returned.
7. If a single user's Login Authentication Attribute value and password binds successfully to the directory, authentication has succeeded.
8. Any successful bind is immediately closed.
Create an LDAP repository
To create a new LDAP repository, right-click LDAP Repositories, and select Add a new
Repository. The details entered on the Authentication Repository dialog depend on the type of LDAP directory that you are using. Policy Studio has default entries for some of the more common LDAP directories, which are available from the drop-down lists. However, you can also connect to alternative LDAP directories.
The following subsections demonstrate how to configure this window for typical user searches on three common LDAP servers:
l Oracle Directory Server
l Microsoft Active Directory Server
l IBM Directory Server
Oracle Directory Server
To configure the Authentication Repository dialog for Oracle Directory Server (formerly iPlanet and Sun Directory Server), use the following settings:
Axway API Gateway 7.5.2
Policy Developer Guide 383
9 External connections
l Repository Name:
Enter a suitable name for this user store.
l Directory Name:
Click Add/Edit to add details of your Oracle Directory Server. For more details, see Configure LDAP directories on page 418.
The User Search Conditions section instructs API Gateway to search the LDAP tree according to the following conditions:
l Base Criteria:
Enter where API Gateway should begin searching the LDAP directory (for example, cn=Users,
dc=qa, dc=vordel, dc=com).
l User Class:
Enter or select the name given by the particular LDAP directory to the User class. For Oracle Directory Server, select 'inetorgperson' LDAP Class.
l User Search Attribute:
The value entered depends on the type of LDAP directory to which you are connecting. When a user is stored in an LDAP directory, a number of user attributes are stored with that user. One of these attributes corresponds to the user name presented by the client for authentication. However, different LDAP directories use different names for that user attribute. For Oracle Directory Server, select cn from the drop-down list.
l Allow Blank Passwords:
Select this to allow the use of blank passwords.
In the next section, you must specify the following:
l Login Authentication Attribute:
In an LDAP directory tree, there must be one user attribute that uniquely distinguishes any one user from all the others. In Oracle Directory Server, the Distinguished name is referred to as the entrydn or Entry Domain Name. Select Entry Domain Name to uniquely identify the client authenticating to API Gateway.
l Authorization Attribute:
When the client has been successfully authenticated, you can use any one of that user's stored attributes in a subsequent authorization filter. In this case, you want to use the user's Entry Domain Name (Distinguished Name) for an authorization filter, so enter entrydn in the text box. However, you can enter any user attribute as long as the subsequent authorization filter supports it. The value of the LDAP attribute specified is stored in the authentication.subject.id message attribute.
l Authorization Attribute Format:
Because any user attribute can be specified in the Authorization Attribute above, you must inform API Gateway of the type of this attribute. API Gateway uses this information internally in subsequent authorization filters. Select X.509 Distinguished Name from the dropdown list.
Axway API Gateway 7.5.2
Policy Developer Guide 384
9 External connections
Microsoft Active Directory Server
This subsection describes how to configure the Authentication Repository dialog for Microsoft Active Directory Server. The values enter here differ from those entered when interfacing to the Oracle Directory Server:
l Repository Name:
Enter a suitable name for this search.
l LDAP Directory:
Click Add/Edit to add details of your Active Directory Server. For more details, see Configure LDAP directories on page 418.
The User Search Conditions instruct API Gateway to search the LDAP tree according to certain criteria. The values specified are different from those selected for Oracle Directory Server, because MS Active Directory Server uses different attributes and classes to Oracle Directory Server:
l Base Criteria:
The base criteria specify the base object under which to search for the user's profile (for example, cn=Users, dc=qa, dc=vordel, dc=com).
l User Class:
In Active Directory Server, the user class is called User, so select 'User' LDAP Class.
l User Search Attribute:
This specifies the name of the user attribute whose value corresponds to the user name entered by the client during a successful authentication process. With Active Directory Server, this attribute is called givenName, which represents the name of the user. Enter givenName in this field.
l Login Authentication Attribute:
Enter the name of the user attribute that uniquely identifies the user in the LDAP directory. This attribute is the DName and is called distinguishedName in Active Directory Server. Select Distinguished Name from the drop-down list to uniquely identify the user. API Gateway authenticates the user name and password presented by the client against the values stored for the user identified in this field.
l Authorization Attribute:
When the client has been successfully authenticated, API Gateway can use any of that user's stored attributes in subsequent authorization filters. Because most authorization filters require a DName, enter Distinguished Name in the text box. However, any user attribute could be entered here, as long as the subsequent authorization filter supports it.
l Authorization Attribute Format:
API Gateway needs to know the format of the Authorization Attribute. Select X.509
Distinguished Name from the drop-down list.
Axway API Gateway 7.5.2
Policy Developer Guide 385
9 External connections
IBM Directory Server
The configuration details for IBM Directory Server provide an example of a directory server that does not return a full DName as the result of a standard LDAP user search. Instead, it returns a contextualized DName, which is relative to the specified Base Criteria. In such cases, API Gateway can build up the full DName by combining the Base Criteria and the returned name. The following example shows how this works in practice.
If C=IE is specified as the Base Criteria, the IBM Directory Server returns CN=niall, OU=Dev, instead of the full DName, which is C=IE, CN=niall, OU=Dev. To enable API Gateway to do this, leave the Login Authentication Attribute field blank. API Gateway then automatically concatenates the specified Base Criteria ( C=IE) with the contextualized DName returned from the directory server ( CN=niall, OU=Dev) to obtain the fully qualified DName ( C=IE,
CN=niall, OU=Dev).
You can also leave the Authorization Attribute field blank to enable API Gateway to automatically use the fully qualified DName for subsequent authorization filters. You should select X.509
Distinguished Name from the Authorization Attribute Format drop-down list.
Oracle Access Manager repositories
You can authorize an authenticated user for a particular resource against an Oracle Access Manager (OAM) repository. After successful authentication, OAM issues a Single Sign On (SSO) token, which can then be used instead of the user name and password.
To authenticate users against an OAM repository, right-click Oracle Access Manager
Repositories, and select Add a new Repository. Configure the following fields on the Authentication Repository dialog:
Repository Name:
Enter an appropriate name for this repository.
Resource Request:
Configure the following settings for the resource request:
l Resource Type:
Enter the type of the resource for which you are requesting access. For example, for access to a Web-based URL, enter http.
l Resource Name:
Enter the name of the resource for which the user is requesting access. By default, this field is set to //hostname${http.request.uri}, which contains the original path requested by the client.
l Operation:
In most access management products, users are authorized for a limited set of actions on the requested resource. For example, users with management roles may be permitted to write ( HTTP
POST) to a certain web service, but users with junior roles might only have read access ( HTTP
GET) to the same service. Use this field to specify the operation to which you want to grant the Axway API Gateway 7.5.2
Policy Developer Guide 386
9 External connections
user access on the specified resource. By default, this is set to the http.request.verb message attribute, which contains the HTTP verb used by the client to send the message to API Gateway (for example, HTTP POST).
l Include query string:
Select whether the query string parameters are used by the OAM server to determine the policy that protects this resource. This setting is optional if the policies configured do not rely on the query string parameters.
l Client location:
If the client location must be passed to OAM for it to make its decision, you can enter a valid DNS name or IP address to specify this location.
l Optional Parameters:
You can add optional additional parameters to be used in the authentication decision. The available optional parameters include the following:
ip
IP address, in dotted decimal notation, of the client accessing the resource.
operation
Operation attempted on the resource (for HTTP resources, one of GET, POST, PUT, HEAD, DELETE, TRACE, OPTIONS, CONNECT, or OTHER).
resource
The requested resource identifier (for HTTP resources, the full URL).
targethost
The host ( host:port) to which resource request is sent.
Note
One or more of these optional parameters may be required by certain authentication schemes, modules, or plugins configured in the OAM server. To determine which parameters to add, see your OAM server configuration and documentation.
Single Sign On:
Configure the following settings for single sign on:
l Create SSO Token:
Select whether to create an SSO token. This is selected by default.
l Store SSO Token in User Attribute:
Enter the name of the message attribute that contains the user's SSO token. This attribute is populated when authenticating to OAM using the HTTP Basic or HTTP Digest filter (see HTTP basic authentication on page 487 and HTTP digest authentication on page 489). By default, the SSO token is stored in the oracle.sso.token message attribute.
l Add SSO Token to User Attributes:
Select whether to add the SSO Token to user message attributes. This is selected by default.
OAM Access Server SDK Directory:
Enter the path to your OAM Access Server SDK directory. For more details on the OAM Access Server SDK, see your OAM documentation.
Axway API Gateway 7.5.2
Policy Developer Guide 387
9 External connections
For more details on using filters to integrate API Gateway with Oracle Access Manager, see Oracle Access Manager filters on page 760.
Oracle Entitlements Server 10g repositories
You can authenticate and authorize a user for a particular resource against an Oracle Entitlements Server (OES) 10g repository. For example, API Gateway can extract credentials from the message sent by the client, and delegate authentication to OES 10g. When the client has been authenticated, API Gateway queries OES 10g to see if the client is permitted to access the web service resource. When authentication and authorization have passed, the message is trusted and forwarded to the target web service.
To authenticate and authorize users against an OES 10g repository, right-click Oracle
Entitlements Server 10g Repositories, and select Add a new Repository. Configure the following fields on the Authentication Repository dialog:
Repository Name:
Enter an appropriate name for this repository.
Oracle SSM Settings:
Click Configure to launch the Oracle Security Service Module Settings dialog. For details on configuring these settings, see Oracle Security Service Module settings (10g) on page 211.
RADIUS repositories
You can configure API Gateway to authenticate users in a Remote Authentication Dial In User Service (RADIUS) repository. RADIUS is a client-server network protocol that provides centralized authentication and authorization for clients connecting to remote services.
To authenticate users against a RADIUS repository, perform the following steps:
1. Right-click RADIUS Repositories, and select Add a new Repository.
2. In the Authentication Repository dialog, enter the RADIUS Repository Name.
3. On the Client tab, select the RADIUS clients that you wish to authenticate to the repository. For details on how to add clients to this list, see Configure RADIUS clients on page 422.
4. On the Attributes tab, click Add to add a RADIUS attribute. This is a name-value pair used to determine how access is granted. Examples include User-Name, User-Password, NAS-
IP-Address, or NAS-Port).
5. In the RADIUS Attributes dialog, enter a Name for the attribute (for example, User-Name). You can select standard RADIUS attributes from the drop-down list, or enter a custom attribute.
6. Enter a Value for the attribute, and click OK.
7. Click OK in the Authentication Repository dialog when you have finished adding attributes.
Axway API Gateway 7.5.2
Policy Developer Guide 388
9 External connections
RSA Access Manager repositories
RSA Access Manager (formerly known as RSA ClearTrust) provides Identity Management and access control services for web applications. It centrally manages access to web applications, ensuring that only authorized users are allowed access to resources. Integration with RSA Access Manager requires RSA Access Manager SDK version 6.2, or server installation libraries.
To authenticate users against an RSA Access Manager repository, right-click RSA Access Manager
Repositories, and select Add a new Repository. Configure the following fields on the Authentication Repository dialog:
Repository Name:
Enter an appropriate name for this repository.
Connection Details:
API Gateway can connect to a group of Access Manager Authorization Servers or Dispatcher Servers. When multiple Access Manager Authorization Servers are deployed for load-balancing purposes, API Gateway first connects to a Dispatcher Server, which returns a list of active Authorization Servers. An attempt is made to connect to one of these Authorization Servers using round-robin DNS. If the first Dispatcher Server in the Connection Group is not available, API Gateway attempts to connect to the Dispatcher Server with the next highest priority in the group, and so on.
If a Dispatcher Server has not been deployed, API Gateway can connect directly to an Authorization Server. If the Authorization Server with the highest priority in the Connection Group is not available, API Gateway attempts to connect to the Authorization Server with the next highest priority, and so on. You can select the type of the Connection Group using the Authorization Server or Dispatcher Server radio button. All servers in the group must be of the same type.
Connection Group:
Select the Connection Group to use for authenticating clients. You can add Connection Groups under the Environment Configuration > External Connections node in Policy Studio. Expand the Connection Sets node, right-click RSA ClearTrust Connection Sets, and select Add a
Connection Set. For more details on adding and editing Connection Groups, see Configure connection groups on page 866.
Authentication Type:
Select one of the following authentication types for the connection:
l HTTP Basic
l Windows NT
l RSA SecureID
l LDAP
l Certificate Distinguished Name
For more details on prerequisites and on using a filter to integrate API Gateway with RSA Access Manager, see RSA Access Manager authorization.
Axway API Gateway 7.5.2
Policy Developer Guide 389
9 External connections
Sun Access Manager repositories
API Gateway can authenticate and authorize users against SunAccess Manager using Access Manager Repositories. When a user has been successfully authenticated, they receive a Single Sign On (SSO) token, which they can use to obtain access to resources that are protected by Access Manager. To authenticate users against a Sun Access Manager repository, right-click Sun Access Manager
Repositories, and select Add a new Repository. Configure the following fields on the Authentication Repository dialog:
Repository Name:
Enter a descriptive name for this repository.
Login Module Name:
Enter the name of the Access Manager Module Instance that is responsible for logging in users. The module entered must be registered with the Realm specified below.
Realm:
Specify the realm that the Access Manager Module Instance specified above belongs to.
Create SSO Token:
Select this check box if you want Sun Access Manager to create an SSO (Single Sign-On) token when a user has successfully authenticated. The user can then use this SSO token to gain access to other resources that are protected by Access Manager.
Store SSO Token in Attribute Named:
Enter the name of API Gateway message attribute in which to store the SSO token. Most of API Gateway's Access Manager integration filters require the name of this attribute to retrieve the SSO token and process it. Add SSO Token to User Attributes:
If this option is selected, the SSO token that is retrieved after successfully authenticating to Sun Access Manager is stored in the attribute.lookup.list message attribute, which contains a list of user attributes. Axway does not recommend selecting this option if you wish to insert a SAML attribute statement into the message (using one of the SAML injection filters) later in the policy. If this option is unselected, the SSO token is inserted into the SAML attribute statement, which may not always be desirable. For this reason, the decision is left to the user on whether or not to add the SSO token to the attribute.lookup.list of user attributes depending on their specific requirements.
Tivoli repositories
API Gateway can integrate with Tivoli Access Manager to authenticate users. To authenticate users against a Tivoli repository, right-click Tivoli Repositories, and select Add a new Repository.
For more details on how to configure API Gateway to communicate with a Tivoli server, see the API Gateway Authentication and Authorization Integration Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 390
9 External connections
Configure Axway PassPort authentication
repositories
Overview
Axway PassPort provides a central repository, identity broker, and security audit point for your Axway Business-to-Business Integration (B2Bi) or Managed File Transfer (MFT) solutions. Axway PassPort centralizes and simplifies provisioning and management for your entire online ecosystem, enabling secure collaboration between applications, divisions, customers, suppliers, and regulatory bodies. To authenticate users against an Axway PassPort repository, in the Policy Studio tree, select Environment Configuration > External Connections > Authentication Repository
Profiles. Right-click Axway PassPort Repositories, and select Add a new Repository. This topic explains how to configure the Axway PassPort repository settings, and provides details on Axway PassPort repository registration.
Configuration
Complete the following fields to configure an Axway PassPort repository:
Repository Name:
Enter a descriptive name for this repository.
Hostname:
Enter the host name or IP address of the server running PassPort.
Shared Secret:
Enter the PassPort shared secret. This is specified during PassPort installation.
CSD Name:
Enter the name of the Axway Component Security Descriptor (CSD) file to use when registering with PassPort. Defaults to csd.xml.
Note
The CSD file must be deployed in the API Gateway group's conf directory in your API Gateway installation:
INSTALL_DIR/apigateway/groups/GROUP_ID/conf
PassPort Certificates—HTTPS:
Select the certificate used for PassPort SSL communication. To export this certificate from PassPort, perform the following steps:
1. In the PassPort user interface, click Administration >Server Security Settings.
2. Note the certificate used for Default_HTTPS.
Axway API Gateway 7.5.2
Policy Developer Guide 391
9 External connections
3. Click Security >Certificates.
4. Select the certificate noted in step 2 (defaults to CN=PassPortSecured,O=Axway,C=FR
), and click Export Certificate.
5. In the Export Certificate dialog, select a File Extension of .cer.
6. Click OK, and select a location to save the certificate.
To import this certificate into the API Gateway, perform the following steps:
1. In the API Gateway Authentication Repository dialog, click Select.
2. In the Select Certificate dialog, click Create/Import.
3. In the Configure Certificate and Private Key dialog, click Import Certificate.
4. Select the certificate that was exported from PassPort.
5. Give the certificate an Alias Name manually, or click Use Subject.
6. Click OK.
7. Select the certificate from the list, and click OK.
PassPort Certificates—HTTPS Client Authentication (Optional):
You can configure PassPort to use a different certificate for its client authentication protocol. To do this, repeat the steps for the HTTPS certificate, except when exporting from PassPort in step 2, make a note of the Default_HTTPS_Client_Auth certificate.
Ports—HTTPS:
Enter the HTTPS port that PassPort is using. In PassPort, this is found under Administration > Server Ports Configuration. Defaults to 6453.
Ports—HTTPS Client Authentication:
Enter the HTTPS client authentication port that PassPort is using. In PassPort, this is found under Administration > Server Ports Configuration. Defaults to 6666.
Authentication—Domain:
Enter the PassPort domain that this repository is using for authentication and authorization. Defaults to Synchrony.
Axway PassPort repository registration
The external connection to Axway PassPort requires that communication with the Axway PassPort server is performed over a secure connection using two-way SSL authentication. This means that the PassPort server must be able to identify and trust the client connection, and this trust is established by registration. The first connection from the API Gateway to PassPort initiates registration. A public-private key pair is created and a Certificate Signing Request (CSR) is submitted to PassPort. This is where the Shared Secret and HTTPS port values are used. While the CSR is pending, the repository is unable to process any requests. However, registration is a once off event, and when complete, it does not need to be repeated. Axway API Gateway 7.5.2
Policy Developer Guide 392
9 External connections
When registration is complete, the key and signed certificate are stored in a Java Key Store file in the following directory of your API Gateway installation:
INSTALL_DIR/apigateway/groups/GROUP_ID/conf
Troubleshooting registration issues
In the unlikely event that automatic registration fails, you should check the following:
l Ensure the time on the API Gateway is synchronized with the time on the PassPort machine. When PassPort processes the CSR, it sets the Valid From date to the current time. If the PassPort time is ahead of the API Gateway time, the API Gateway is unable to use the certificate because it is not yet valid. The error in the trace log is as follows:
java.security.cert.CertificateNotYetValidException:java.security.cert.Certificate
NotYetValidException
l By default, PassPort blocks for up to 2 seconds waiting for the CSR to be processed. You can configure this value in the PassPort administration user interface under Administration > System Properties ( am.registration.cert.signature.wait.time). If the signing request takes longer than this, one of the following errors may be logged:
Authentication exception when authenticating system:
com.axway.passport.am.api.v2.service.external.PassportConnectionException:Registr
ation is still in progress.
Certificate Signing Request has not yet been validated, please try again later.
[Status:Waiting Validation]
Authentication exception when authenticating system:
com.axway.passport.am.api.v2.service.external.PassportConnectionException:Registr
ation is still in progress.
Certificate Signing Request has not yet been signed, please try again later.
[Status:Waiting Signing]
This is generally a transient error that may be generated when the initial registration is in progress. Resubmitting the request should succeed. If the error persists, check in the PassPort administration user interface for the reason why the signing request has been delayed. l If the registration request has been refused by the PassPort administrator, the following error is displayed:
Registration has been refused.
Please contact the PassPort Administrator for further information.
[Status:Validation Refused]
l If CSR processing fails for some other reason, the following error is logged:
Axway API Gateway 7.5.2
Policy Developer Guide 393
9 External connections
Registration has failed and API Gateway is unable to communicate with PassPort.
Please contact the PassPort Administrator or try manually re-triggering
registration.
[Status:...]
To resolve this, contact the PassPort administrator to see why the signing request failed. To retry registration, you need to manually re-trigger registration, as explained in the next subsection.
Retrigger registration manually
When registration is complete, the API Gateway does not repeat the process, the generated Java Key Store (JKS) is used for all subsequent connection attempts. However, if for any reason the key pair in the JKS is no longer trusted by PassPort, or if registration is not being processed, you can trigger the registration procedure manually.
The simplest way to retrigger registration is to change the repository name and redeploy. However, if this is not an option, you can manually remove the keystores.
The format of the JKS file names is as follows:
keystore_REPOSITORYNAME_HOSTNAME_HTTPSCLIENTAUTHPORT.jks
All non-alphanumerics are replaced with an underscore ( _). For example, given the following repository details: l Repository Name: PassPort - local
l Hostname: passport-host
l HTTPS Client Authentication: 6666
The keystore name is keystore_PassPort___local_passport_host_6666.jks.
To trigger registration, perform the following steps:
1. Back up the JKS associated with the Axway PassPort Authentication Repository being reset.
2. Delete this JKS.
3. Restart the API Gateway instance. The deleted file is recreated and registration is initiated.
Note
If registration has not been completed when the registration is being retriggered, you must delete the following additional temporary files to ensure clean registration: keystore_REPOSITORYNAME_HOSTNAME_HTTPSCLIENTAUTHPORT.jks.csrid
keystore_REPOSITORYNAME_HOSTNAME_HTTPSCLIENTAUTHPORT.jks.pub
keystore_REPOSITORYNAME_HOSTNAME_HTTPSCLIENTAUTHPORT.jks.key
In addition, to avoid future confusion, it is good practice to ensure that all redundant certificates and signing requests are removed from PassPort using the PassPort Axway API Gateway 7.5.2
Policy Developer Guide 394
9 External connections
administration user interface.
Configure client credentials
Overview
Client credentials enable you to globally configure client authentication settings for the following authentication options:
l API keys as a client
l HTTP basic
l Kerberos
l OAuth 2.0 as a client
Note
For more information on configuring OAuth 2.0 client credentials, see the API Gateway OAuth User Guide. You can configure settings for client credentials under the Environment Configuration >
External Connections > Client Credentials node in the Policy Studio tree, which you can then specify at the filter level, for example, in the Connection and Connect To URL filters. Configure API key client credential profiles
API key client credential profiles enable you to globally configure authentication settings for API keys as a client. API keys are supplied by client users and applications calling REST APIs to allow the API service provider to track and control how the APIs are used (for example, to meter access and prevent abuse or malicious attack). To configure API key client credential profiles, you must first configure a provider. The following Amazon Web Services provider configurations are included in an out-of-the-box installation of API Gateway:
l Amazon AWS V2 Signing
l Amazon AWS V4 Signing
Add API keys
To add an API key for an existing API key provider, click an API key client credential node (for example, Amazon AWS V2 Signing), and click the Add button on the API Key Credential
Profiles tab of the API Key Credential Profile window. Complete the following fields on the Add API Key dialog:
Name:
Enter a suitable name for this API key.
Axway API Gateway 7.5.2
Policy Developer Guide 395
9 External connections
API Key ID:
Enter an identifier for this API key. This is the Amazon client ID associated with your Amazon account. API Key Secret:
Enter a secret for this API key. This is the Amazon secret associated with your Amazon account.
Tip
To sort the list view of client credential profiles, click the column heading. After you have configured your API key client credentials globally, you can select the client credential profile to use for authentication on the Authentication tab of your filter (for example, in the Connection and Connect To URL filters). For more information, see Connection on page 786 and Connect to URL on page 780.
Add API key providers
To configure a new API key provider, right-click API Keys, and select Add API Key Client
Credential. Complete the following fields on the API Key Service Provider Configuration dialog:
Name:
Enter a suitable name for this API key service provider configuration.
Sign the request using:
Select an option to specify how the request is signed. The options are:
l Amazon Access Key Signing V2
l Amazon Access Key Signing V4
l No Signing
Put the API key in:
Select an option to specify where to put the API key in the request and enter a name in the named field. The options are: l Header – The parameter is added to the header of the request. l Query String/Form Body – If the incoming request is a GET request, the parameter is added to the query string. If the incoming request is a POST request, the parameter is added to the content body.
Note
Version 2 of the Amazon Signing API only supports the GET operation and only recognizes a limited set of query string parameters. Any unsupported query string parameters result in a HTTP 400 Bad Request response from the V2 Amazon web service.
For example, to put the API key in the header of the request in a field named AWSKeyId, choose Header and enter AWSKeyId.
Tip
To change the configuration of an existing API key service provider, click the API key client credential node, and edit the settings on the API Key Configuration tab of the API Key
Credential Profile window.
Axway API Gateway 7.5.2
Policy Developer Guide 396
9 External connections
Configure HTTP basic/digest client credential
profiles
A client can authenticate to the API service provider with a user name and password combination using HTTP basic authentication or HTTP digest authentication. To add a HTTP basic/digest client credential profile, click the HTTP Basic node, and click the Add button on the HTTP Basic/Digest Client Credentials window. Complete the following fields on the Add HTTP Authentication Profile dialog:
Profile Name:
Enter a suitable name for this HTTP authentication profile.
Choose Authentication Type:
Select the Basic or Digest radio button to specify the type of HTTP authentication to use, and enter a user name and password in the Username and Password fields.
Automatically send credentials:
Select this option to automatically send credentials in the request. This is the equivalent of Send
token with first request in Kerberos. This option is selected by default.
After you have configured your HTTP client credentials globally, you can select the client credential profile to use for authentication on the Authentication tab of your filter (for example, in the Connection and Connect To URL filters). For more information, see Connection on page 786 and Connect to URL on page 780.
Configure Kerberos client credential profiles
A Kerberos client can authenticate to a Kerberos service by sending a Kerberos service ticket in the HTTP request to that service. Note
You can also configure the API Gateway to authenticate to a Kerberos service by including the relevant Kerberos tokens inside the XML message. For more details, see Kerberos client authentication on page 505. For more details on different Kerberos setups with API Gateway, see API Gateway Kerberos Integration Guide.
To add a credential profile for a Kerberos client, click Kerberos, and select Add in the Kerberos
Client Credentials window. Configure the following fields on the Add Kerberos Profile dialog:
Profile Name:
Enter a suitable name for this Kerberos authentication profile.
Kerberos Client:
Click the ... button, and select a previously configured Kerberos client from the list. To add a Kerberos client, right-click Kerberos Clients, and select Add Kerberos Client. You can also add Kerberos clients globally under Environment Configuration > External Connections in the node tree.
Axway API Gateway 7.5.2
Policy Developer Guide 397
9 External connections
The selected Kerberos client has two roles. First, it must obtain a Kerberos Ticket Granting Ticket (TGT). Second, it uses this TGT to obtain a service ticket for the Kerberos Service Principal selected in this profile. For more details on configuring Kerberos clients, see Configure Kerberos clients on page 407. Kerberos Service Principal:
Click the ... button, and select a previously configured Kerberos service principal from the list. To add a Kerberos principal, right-click Kerberos Principals, and select Add Kerberos Principal. You can also add Kerberos principals under Environment Configuration > External
Connections in the node tree.
The Kerberos client must obtain a ticket from the Kerberos Ticket Granting Server (TGS) for the selected Kerberos service principal. The TGS grants a ticket for the principal, and the Kerberos client can then send the ticket to the Kerberos service. The principal in the ticket must match the principal of the Kerberos service for the client to be successfully authenticated. A service principal name (SPN) can be used to uniquely identify the service in the Kerberos realm. For more details on configuring Kerberos principals, see Configure Kerberos principals on page 412. Send token with first request:
In some cases, a Kerberos client might not authenticate (send the Authorization HTTP header) to the Kerberos service on first request. The Kerberos service then responds with an HTTP 401 response code, instructing the client to authenticate to the server by sending the Authorization header. The Kerberos client sends a second request, this time with the Authorization header containing the relevant Kerberos token. Select this option to always send the Authorization HTTP header containing the Kerberos service ticket on the first request to the Kerberos service. This option is selected by default.
Send body only after establish context:
Select this option if you want the Kerberos client to only send the message body after the context with the Kerberos service has been fully established (the client has mutually authenticated with the service).
Pass when service returns 200 even if context not established:
In rare cases, a Kerberos service might return a 200 OK response to the initial request from a Kerberos client even though the security context has not yet been fully established. This 200 OK response might not contain the WWW-authenticate HTTP header. Select this option to send the request with the Authorization header to the Kerberos service even if the context has not been established. The Kerberos service then decides whether to process the request depending on the status of the security context.
After you have configured your Kerberos client credentials profile globally, you can select the client credential profile to use for authentication on the Authentication tab of your filter (for example, in the Connection and Connect To URL filters). For more information, see Connection on page 786 and Connect to URL on page 780.
Axway API Gateway 7.5.2
Policy Developer Guide 398
9 External connections
Configure database connections
Overview
The details entered on the Configure Database Connection dialog specify how the API Gateway connects to the database. The API Gateway maintains a JDBC pool of database connections to avoid the overhead of setting up and tearing down connections to service simultaneous requests. This pool is implemented using Apache Commons DBCP (Database Connection Pools) . The settings in the Advanced - Connection pool section of this window configures the database connection pool. For details on how the fields on this window correspond to specific DBCP configuration settings, see the table in Database connection pool settings on page 401.
Prerequisites
Before configuring a database connection, you must add the JDBC driver files for your chosen database to your API Gateway and Policy Studio installations. The following sections show how to add the third-party JDBC driver files for your database to API Gateway and Policy Studio.
Add third-party binaries to API Gateway
To add third-party binaries to API Gateway, perform the following steps:
1. Add the binary files as follows:
l Add .jar files to the INSTALL_DIR/apigateway/ext/lib directory.
l Add .dll files to the INSTALL_DIR\apigateway\Win32\lib directory.
l Add .so files to the INSTALL_DIR/apigateway/<platform>/lib directory.
2. Restart API Gateway.
Add third-party binaries to Policy Studio
To add third-party binaries to Policy Studio, perform the following steps:
1. Select Windows > Preferences > Runtime Dependencies in the Policy Studio main menu.
2. Click Add to select a JAR file to add to the list of dependencies.
3. Click Apply when finished. A copy of the JAR file is added to the plugins directory in your Policy Studio installation.
4. Click OK.
5. Restart Policy Studio with the -clean option. For example:
> cd INSTALL_DIR/policystudio/
Axway API Gateway 7.5.2
Policy Developer Guide 399
9 External connections
> policystudio -clean
Configure the database connection
Configure the following fields on the Configure Database Connection window:
Name:
Enter a name for the database connection in the Name field.
URL:
Enter the fully qualified URL of the location of the database. The following table shows examples of database connection URLs, where reports is the name of the database and DB_HOST is the IP address or host name of the machine on which the database is running:
Database
Example Connection URL
Oracle
jdbc:oracle:thin:@DB_HOST:1521:reports
Microsoft SQL
Server
jdbc:sqlserver://DB_
MySQL
jdbc:mysql://DB_HOST:3306/reports
IBM DB2
jdbc:db2://DB_HOST:50000/reports
HOST:1433;DatabaseName=reports;
integratedSecurity=false;
User Name:
The user name to use to access the database.
Password:
The password for the user specified in the User Name field.
Initial pool size:
The initial size of the DBCP pool when it is first created.
Maximum number of active connections:
The maximum number of active connections that can be allocated from the JDBC pool at the same time. The default maximum is 8 active connections.
Maximum number of idle connections:
The maximum number of active connections that can remain idle in the pool without extra connections being released. The default maximum is 8 connections.
Minimum number of idle connections:
The minimum number of active connections that can remain idle in the pool without extra connections being created. The default minimum is 8 connections.
Axway API Gateway 7.5.2
Policy Developer Guide 400
9 External connections
Maximum wait time:
The maximum number of milliseconds that the pool waits (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely. The default time is 10000ms, and a value of -1 indicates an indefinite time to wait.
Time between eviction:
The number of milliseconds to sleep between runs of the thread that evicts unused connections from the JDBC pool.
Number of tests:
The number of connection objects to examine from the pool during each run of the evictor thread. The default number of objects is 3.
Minimum idle time:
The minimum amount of time, in milliseconds, an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any). Database connection pool settings
The table below shows the correspondence between the fields in the Advanced - Connection
pool section of the window and the Apache Commons DBCP configuration properties:
Field Name
DBCP Configuration Property
URL
url
User Name
username
Password
password
Initial pool size
initialSize
Maximum number of active connections
maxActive
Maximum number of idle connections
maxIdle
Minimum number of idle connections
minIdle
Maximum wait time
maxWait
Time between eviction
timeBetweenEvictionRunsMillis
Number of tests
numTestsPerEvictionRun
Minimum idle time
minEvictableIdleTimeMillis
Axway API Gateway 7.5.2
Policy Developer Guide 401
9 External connections
Connection validation
By default, when the API Gateway makes a connection, it performs a simple connection validation query. This enables the API Gateway to test the database connection before use, and to recover if the database goes down (for example, if there is a network failure, or if the database server reboots). The API Gateway validates connections by running a simple SQL query (for example, a SELECT 1 query with MySQL). If it detects a broken connection, it creates a new connection to replace it.
Test the connection
When you have specified all the database connection details, you can click the Test Connection button to verify that the connection to the database is configured successfully. This enables you to detect any configuration errors at design time instead at runtime. Configure database queries
Overview
The Database Statement dialog enables you to enter an SQL query, stored procedure, or function call that the API Gateway runs to return a specific user's profile from a database.
Configuration
The following fields should be completed on this window:
Name:
Enter a name for this database query here.
Database Query:
Enter the actual SQL query, stored procedure, or function call in the text area provided. When executed, the query should return a single user's profile. The following are examples of SQL statements and stored procedures:
select * from users where username=${authentication.subject.id}
{ call load_user (${authentication.subject.id}, ${out.param}) }
{ call ${out.param.cursor} := p_test.f_load_user(${authentication.subject.id}) }
These examples show that you can use selectors in the query. The selector that is most commonly used in this context is ${authentication.subject.id}, which specifies the message attribute that holds the identity of the authenticated user. For more details on selectors, see Select configuration values at runtime on page 854.
Axway API Gateway 7.5.2
Policy Developer Guide 402
9 External connections
Statement Type:
The database can take the form of an SQL query, stored procedure, or function call, as shown in the above examples. Select the appropriate radio button depending on whether the database query is an SQL Query or a Stored procedure/function call.
Table Structure:
To process the result set that is returned by the database query, the API Gateway needs to know whether the user's attributes are structured as rows or columns in the database table.
The following example of a database table shows the user's attributes (Role, Dept, and Email) structured as table columns:
Username
Role
Dept
Email
Admin
Administrator
Engineering
[email protected]
Tester
Testing
QA
[email protected]
Dev
Developer
Engineering
[email protected]
In the following table, the user's attributes have been structured as name-value pairs in table rows:
Username
Attribute Name
Attribute Value
Admin
Role
Administrator
Admin
Dept
Engineering
Admin
Email
[email protected]
Tester
Role
Testing
Tester
Dept
QA
Tester
Email
[email protected]
Dev
Role
Developer
Dev
Dept
Engineering
Dev
Email
[email protected]
If the user's attributes are structured as column names in the database table, select the attributes
as column names radio button. If the attributes are structured as name-value pair in table rows, select the attribute name-value pairs in rows option.
Axway API Gateway 7.5.2
Policy Developer Guide 403
9 External connections
Configure ICAP servers
Overview
The Internet Content Adaptation Protocol (ICAP) is a lightweight HTTP-based protocol used to optimize proxy servers, which frees up resources and standardizes how features are implemented. For example, ICAP is typically used to implement features such as virus scanning, content filtering, ad insertion, or language translation in the HTTP proxy server cache. Content Adaptation refers to performing a specific value-added service (for example, virus scanning) for a specific client request and/or response.
You can configure ICAP servers under the Environment Configuration > External
Connections tree node, which you can then specify in an ICAP filter later. To configure an ICAP server, right-click the ICAP Servers node, and select Add an ICAP Server to display the ICAP
Server Settings dialog.
Server settings
Configure the following settings on the Server tab:
Host
The machine name or IP address of the remote ICAP host. Defaults to the localhost ( 127.0.0.1).
Port
The port on which the ICAP server is listening. Defaults to 1344.
Request
Service
The path to the service (exposed by the ICAP server) that handles Request Response
Service
The path to the service exposed by the ICAP server that handles Response Options
Service
The path to the service (exposed by the ICAP server) that handles OPTIONS requests. OPTIONS requests enable server capabilities to be queried. The default Modification (REQMOD) requests. The default value is /request.
Modification (RESPMOD) requests. The default value is /response.
value is /options.
Security settings
The following settings on the Security tab enable you to secure the connection to the ICAP server:
Trusted Certificates:
When the API Gateway connects to the ICAP server over SSL, it must decide whether to trust the ICAP server's SSL certificate. You can select a list of CA or server certificates on the Trusted
Axway API Gateway 7.5.2
Policy Developer Guide 404
9 External connections
Certificates tab that are considered trusted by API Gateway when connecting to the ICAP server. The table displayed on the Trusted Certificates tab lists all certificates imported into the API Gateway Certificate Store. To trust a certificate for this particular connection, select the box next to the certificate in the table. Client SSL Authentication:
In cases where the destination ICAP server requires clients to authenticate to it using an SSL certificate, you must select a client certificate on the Client SSL Authentication tab. Select the check box next to the client certificate that you want to use to authenticate to the ICAP server.
Advanced:
The Ciphers field enables you to specify the ciphers that API Gateway supports. The API Gateway sends this list of supported ciphers to the destination ICAP server, which then selects the highest strength common cipher as part of the SSL handshake. The selected cipher is then used to encrypt the data when it is sent over the secure channel.
Advanced settings
Select one of the following ICAP server modes on the Advanced tab:
Request
Modification
Mode
(REQMOD)
Specifies that the ICAP filter in the API Gateway sends a Request Modification (REQMOD) request to the ICAP server. The ICAP server returns a modified version of the request, an HTTP response, or a 204 response code indicating that no modification is required. This mode is selected by default.
Response
Modification
Mode
(RESPMOD)
Specifies that the ICAP filter in the API Gateway sends a Response Modification (RESPMOD) request to the ICAP server. For example, the API Gateway sends an origin server's HTTP response to the ICAP server. The response from the ICAP server can be an adapted HTTP response, an error, or a 204 response code indicating that no adaptation is required.
Further information
For example policies that show an ICAP filter configured in REQMOD and RESPMOD modes, see Send to ICAP on page 596.
Axway API Gateway 7.5.2
Policy Developer Guide 405
9 External connections
Configure Sentinel servers
Sentinel server overview
Axway Sentinel is a Business Activity Monitoring (BAM) product that collects, aggregates, correlates, and reports events from API Gateway and other Axway products, applications, and systems throughout your infrastructure. Sentinel is a separate product that you can buy from Axway or an authorized partner. This topic describes how you can configure API Gateway to send events to Axway Sentinel server. Note
A complete documentation set for Axway Sentinel is available on the Axway Support website: https://support.axway.com.
To add a new Sentinel server connection, in the Policy Studio tree, under the Environment
Configuration > External Connections node, right-click the Sentinel Servers node, and select Add a Sentinel Server.
General settings
You can configure the following general settings for the Sentinel server:
Name:
Enter a suitable name for this Sentinel server. Host:
Enter the host name (FQDN) or IP address of the Sentinel server. Port:
Enter the port number that the Sentinel server is listening for events on. Use overflow file:
Select this option to use an overflow file to store API Gateway event data when there is no connection between API Gateway and Sentinel.
Name:
Enter a suitable name for the overflow file. Size (MB):
Enter the maximum size of the overflow file. Encoding:
Enter the encoding type to use. The default is utf-8. User agent settings:
By default API Gateway registers events against the API Gateway's name in the topology. To use another name, select the Or the following name option and enter an alternative name to use. Axway API Gateway 7.5.2
Policy Developer Guide 406
9 External connections
By default API Gateway registers events against the host name of the machine running the API Gateway. To use another host name, select the Or the following name option and enter an alternative host name to use. Further information
For more detailed information, see the API Gateway Sentinel Interoperability Guide .
Configure Kerberos clients
Overview
API Gateway can act as a Kerberos client. For this, it must authenticate to the Kerberos Key Distribution Center (KDC) as a specific Kerberos principal, and use the Ticket Granting Ticket (TGT) granted for it to obtain tickets from the Ticket Granting Service (TGS) to authenticate to Kerberos services.
You can configure Kerberos clients globally under Environment Configuration > External
Connections in the node tree. Right-click the Kerberos Clients node in the tree, and select Add
a Kerberos Client. The following sections describe how to configure the different fields int he dialog.
Once finished, you can select the configured Kerberos client when configuring other Kerberosrelated filters. Ensure the check box Enabled at the bottom of the window is selected.
For more details on different Kerberos setups with API Gateway, see API Gateway Kerberos Integration Guide.
Kerberos endpoint settings
Configure the following fields on the Kerberos Endpoint tab:
Ticket Granting Ticket Source
This option defines where to obtain the Kerberos client credentials and the session key used in communications with the TGS to request TGTs. A TGT can be retrieved from a cache created as part of a Java Authentication and Authorization Service (JAAS) login, from delegated credentials, or from the native GSS Library on UNIX/Linux platforms.
Note
Depending on the TGT source option option you select, the Kerberos Principal, Password, and Keytab File fields below might be required o r disabled.
Axway API Gateway 7.5.2
Policy Developer Guide 407
9 External connections
Load via JAAS Login:
By default, API Gateway performs a JAAS login to the Kerberos KDC. After the login, API Gateway caches the credentials, and they are used to acquire TGTs as needed. The JAAS login acquires the credentials in one of the following ways:
l Request from KDC – Request a new TGT from the Kerberos KDC. The request is sent at server startup, server refresh (for example, when an update to configuration is deployed), and when the TGT expires.
l Extract from Default System Ticket Cache – If a TGT has already been obtained outside API Gateway and has been stored in the default system ticket cache, you can use this option to retrieve the TGT from the cache. On Windows 2000, the TGT is extracted from the cache using the Local Security Authority (LSA) API. On UNIX/Linux, the assumed default location of the ticket cache is /tmp/krb5cc_<uid> , where <uid> is a numeric user identifier. If the ticket cache cannot be found in the default locations, or on a different Windows platform, API Gateway searches the cache in {user.home}{file.separator}krb5cc_
{user.name}.
Note
A system ticket cache can only hold the credentials of a single Kerberos client. To load credentials for more than one Kerberos client from system ticket caches, select Extract from System Ticket Cache option.
l Extract from System Ticket Cache – Extract the TGT from an explicitly named system ticket cache instead of the default system ticket cache.To specify the cache, browse to the cache you want to use. You can populate ticket caches with client credentials using an external utility, such as kinit.
Load from Delegated Credentials:
The Kerberos client can use a delegated TGT that has been already retrieved from a Kerberos
Service authentication filter. The TGT is extracted from message attributes (for example, authentication.delegated.credentials and authentication.delegated.credentials.client.name) that have been set by the Kerberos Service filter. If you select this option, it is not necessary to configure the Kerberos Principal or Secret Key fields. Load via Native GSS Library:
Select this option to use the Native GSS-API to acquire the client's credentials. The Native GSS-API expects that the credentials already are in a system ticket cache that it can access.
The Load via Kinit option determines the number of Kerberos clients you can use with API Gateway:
l If Load via Kinit is selected, API Gateway can support multiple Kerberos clients natively. API Gateway runs kinit and creates a ticket cache for each client in the /conf/plugins/kerberos/cache directory. The Native GSS-API can automatically acquire the client credentials from these caches. Axway API Gateway 7.5.2
Policy Developer Guide 408
9 External connections
l If Load via Kinit is not selected, API Gateway can support only one Kerberos client natively. The Kerberos client credentials must be in the default system ticket cache. API Gateway cannot support accessing credentials natively from the default system ticket cache and other system ticket caches.
Note
To use the native GSS library and the kinit tool, you must select to use the native GSS library on the instance-level API Gateway Kerberos Configuration settings. For more details, see Kerberos configuration on page 214. Kerberos Principal
A Kerberos principal is used to assign a unique identity for API Gateway to be used in the Kerberos environment. To select which Kerberos principal to use, click the ... button, and select a previously configured principal from the list. To add a Kerberos principal, right-click Kerberos Principals, and select Add Kerberos Principal. You can also add Kerberos principals under Environment
Configuration > External Connections in the node tree.
For Kerberos constrained delegation (KCD), the Kerberos Principal selected here must be configured for credential delegation to a set of Kerberos services in the Kerberos KDC.
For more details, see Configure Kerberos principals on page 412. Note
The semantics of this field are slightly different depending on what TGT source you selected: l If you selected to retrieve the TGT from the KDC, you are effectively asking the KDC to issue a TGT for the principal selected here. l If you selected to retrieve the TGT from a system ticket cache, the principal selected here searches the cache to retrieve the TGT. l If you selected to use the kinit utility, the name of the principal selected here is passed as an argument to kinit. l If you selected to retrieve a TGT from delegated credentials, it is not necessary to specify any principal.
Secret Key
The Kerberos principal uses the secret key to communicate with the KDC's Authentication Service in order to acquire a TGT. The secret key can be generated from a password, or it can be acquired from the principal's keytab file. The options available depend on what you selected as the source of the TGT. Enter Password:
You can only enter a password if you selected to request the TGT from the KDC. The password is used when generating the secret key. A secret key is not required if the TGT has been already retrieved either from a system ticket cache or from delegated credentials. Axway API Gateway 7.5.2
Policy Developer Guide 409
9 External connections
Note
By default, the password entered here is stored in clear-text form in the underlying configuration data in API Gateway. If necessary, the password can be encrypted using a passphrase. For more details on encrypting sensitive API Gateway configuration data, see the API Gateway Administrator Guide.
Wildcard Password:
##enter stuff here Keytab:
If you selected to request the TGT from the KDC, you can also extract the secret key for the principal from a keytab file, which maps principal names to encryption keys. Using the kinit tool also requires a keytab file. To load the principal-to-key mappings into the table in the dialog, select Load Keytab and browse to the existing keytab file. To add a new keytab entry, select Add Principal. To delete a keytab entry, select the entry in the table and click Delete Entry. To export the entire contents of the keytab table in the dialog, click Export Keytab. Note
By default, the contents of the keytab table – derived from a keytab file or manually entered – stored in clear-text form in the underlying configuration data in API Gateway. If necessary, the contents of the keytab table can be encrypted using a passphrase. For more details on encrypting sensitive API Gateway configuration data, see the API Gateway Administrator Guide.
When API Gateway starts, it writes the stored keytab contents to the /conf/plugin/kerberos/keytabs/ directory in your API Gateway installation. It is recommended to configure directory-based or file-based access control for this directory and its contents. For more details on configuring the Keytab Entry dialog, see the Kerberos keytab concepts on page 417.
Kerberos Constrained Delegation settings
An end user application requesting a TGT for a back-end Kerberos service might be unable to authenticate to the Kerberos service with Kerberos credentials, for example, if accessing the service from outside the Kerberos domain. KCD enables the Kerberos principal you selected on the Kerberos Endpoint tab to act as a trusted Kerberos principal. The trusted Kerberos principal authenticates the end user application using some other authentication method than Kerberos credentials, then authenticates to the back-end Kerberos service as the end user application, and acquires a TGT in the name of the end user application.
To enable KCD, configure the following fields on the Kerberos Constrained Delegation tab:
Kerberos Principal to Impersonate:
Select the end user principal being impersonated. The principal to impersonate is normally configured using a selector, so that many end user principals can be impersonated. A typical setup might be that the principal on the Kerberos Endpoint tab might be, for example, [email protected] and the Kerberos Principal to Impersonate is ${authentication.subject.id}@AXWAY.COM.
Axway API Gateway 7.5.2
Policy Developer Guide 410
9 External connections
If you don't set this field, the Kerberos Client does not attempt to impersonate other Kerberos principals in Kerberos Constrained Delegation.
Select Cache for Impersonated Subjects:
Select the cache used to store impersonated user credentials. These will be refreshed automatically so that expired credentials are not sent to the service-side.
You must define this field for KCD.
Advanced settings
You can configure the following fields o n the Advanced tab:
Mechanism:
Select the mechanism used to establish a context between the Kerberos client and the Kerberos service. The Kerberos service must use the same mechanism.
Mutual Authentication:
Select this to carry out mutual authentication . This means that the service authenticates back to the client during the context setup. For SPNEGO mechanism, you must select this.
Integrity:
Select to enable data integrity for GSS operations. Confidentiality:
Select to enables data confidentiality for GSS operations.
Credential Delegation:
Select this to delegate the request initiator's credentials to the acceptor during context setup. If you select this option, the acceptor can assume the initiator's identity and authenticate to other Kerberos services on behalf of the initiator.
Anonymity:
Select to prevent disclosing the Kerberos client's identity to the Kerberos service.
Replay Detection:
Select to enable replay detection for the per-message security services after context establishment.
Sequence Checking:
Select to switch on sequence checking for the per-message security services after context establishment.
Synchronize to Avoid Replays Errors at Service:
If a Kerberos client is running under stress and is attempting to send many requests to a Kerberos service within a very short (millisecond) time frame, the sequential Kerberos Authenticator tokens the Kerberos client generates might contain identical values for the ctime (the current time on the client's host) and cusec (the microsecond portion of the client's timestamp) fields.
Axway API Gateway 7.5.2
Policy Developer Guide 411
9 External connections
Since Kerberos service implementations often compare the ctime and cusec values on successive Kerberos Authenticator tokens to discover replay attacks, it is possible that the Kerberos service might reject Kerberos Authenticator requests in which the ctime and cusec fields have the same value. To avoid this scenario, you can select this option to synchronize the creation of the Kerberos Authenticator requests using the Pause Time value. Note
Select this option only on Windows. On UNIX/Linux, this setting is not required, so ensure it is deselected for better performance.
Pause Time:
Specify the time interval (in milliseconds) to wait before generating the client-side Kerberos Authenticator tokens when synchronizing to avoid over-zealous replay detection on the Kerberos service. You can only set this value if you have also selected the Synchronize to Avoid Replays
Errors at Service option.
Note
The default value of 15 milliseconds matches the clock resolution time of operating systems such as Windows. For more details on the clock resolution on your target operating system, consult your operating system documentation .
Refresh credential when remaining validity is X secs:
Select this to enable refresh the Kerberos credentials shortly before they expire to avoid expiry failures on the service-side.
When API Gateway receives a request that uses a Kerberos client, API Gateway refreshes any cached Kerberos credentials used to process that request, if the time that this credential can be validly used is less than or equal to this number of seconds. It is possible that a credential is only refreshed long after it has expired, as triggering the refresh requires a request that uses the expired credential.
Configure Kerberos principals
Overview
A Kerberos principal represents a unique identity in a Kerberos system to which Kerberos can assign tickets to access Kerberos-aware services. Principal names are made up of several components separated with the / separator. You can also specify a Kerberos realm as the last component of the name by using the @ character. If no realm is specified, the principal is assumed to belong to the default realm, as configured in the krb5.conf file. For more details, see Kerberos configuration on page 214.
Typically, a principal name comprises three parts: the primary, the instance, and the realm. The format of a typical Kerberos v5 principal name is:
primary/[email protected]
Axway API Gateway 7.5.2
Policy Developer Guide 412
9 External connections
l Primary:
If the principal represents a user in the system, the primary is the user name of the user. Alternatively, for a host, the primary is specified as the host string.
l Instance:
The instance can be used to further qualify the primary (for example, user/[email protected]).
l Realm:
This is your Kerberos realm, which is usually a domain name in upper case letters. For example, the foo.abc.com machine is in the ABC.COM Kerberos realm.
For more details on different Kerberos setups with API Gateway, see API Gateway Kerberos Integration Guide.
Configuration
You can configure Kerberos principals globally under the Environment Configuration > External Connections in the node tree. To configure a Kerberos principal, right-click the Kerberos Principals node, and select Add a Kerberos Principal. Configure the following fields on the Kerberos Principal dialog:
Name:
Enter a friendly name for the Kerberos principal. This name is shown in the drop-down lists in other Kerberos-related configuration windows in the Policy Studio.
Principal Name:
Enter the name of the Kerberos principal in this field. The principal name consists of a number of components separated using the / separator. Specify the realm here if the principal belongs to either a non-default realm or if a default realm is not specified in the krb5.conf file.
Principal Type:
Select the type of principal specified in the field above. The following table lists the available principal types. Note
The principal name types and their corresponding OIDs are defined in the General Security Services API (GSS-API). Principal
name type
Explanation
OID
NT_USER_
The principal name identifies a named user on the local system
1.2.840.113554.1.2.1.1
The principal name represents a Kerberos version 5 principal.
1.2.840.113554.1.2.2.1
NAME
KERBEROS_
V5_
PRINCIPAL_
NAME
Axway API Gateway 7.5.2
Policy Developer Guide 413
9 External connections
Principal
name type
Explanation
OID
NT_EXPORT_
The principal name represents an exported canonical byte representation of the name (for example, which can be used when searching for the principal in an Access Control List (ACL)).
1.3.6.1.5.6.4
The principal name identifies a service associated with a specific host.
1.3.6.1.5.6.2
NAME
NT_
HOSTBASED_
SERVICE
To add new principal types, click Add. The name entered in the Name field on the Kerberos
Principal Name OID must correspond to one of the constant fields defined in the org.ietf.jgss.GSSName Java class. For other allowable name types, see the Javadocs for the GSSName class. Similarly, the corresponding OID for this name type must be entered in the OID field of the dialog. Note
OIDs and principal type names must only be changed to reflect changes in the underlying GSS-API. Because of this, do not edit the existing Principal Types except under strict supervision by the Axway Support.
Configure Kerberos services
Overview
API Gateway can act as a Kerberos service. A Kerberos client must obtain a Ticket Granting Ticket (TGT) to authenticate to the Kerberos service exposed by API Gateway. The Kerberos client must present the TGT to API Gateway to be successfully authenticated, and for their requests to be processed. The Kerberos service is responsible for consuming the TGT. You can configure Kerberos services globally under the Environment Configuration > External
Connections in the node tree. To configure a Kerberos service, right-click Kerberos Services, and select Add a Kerberos Service. The following sections describe how to configure the various fields o n the Kerberos Service dialog.
You can select globally configured Kerberos services b y name when configuring a Kerberos
Service filter. This filter is responsible for validating the TGTs consumed by the Kerberos service. To easily tell different Kerberos services apart, ensure you enter a descriptive name for the service in the Name when configuring a Kerberos service. For more details on configuring the Kerberos Service filter, see Kerberos service authentication on page 507. Once finished, you can select the configured Kerberos service when configuring other Kerberosrelated filters. Ensure the check box Enabled at the bottom of the window is selected.
Axway API Gateway 7.5.2
Policy Developer Guide 414
9 External connections
For more details on different Kerberos setups with API Gateway, see API Gateway Kerberos Integration Guide.
Kerberos endpoint settings
Configure the following fields on the Kerberos Endpoint tab:
Kerberos Principal
Select the name of the Kerberos principal you want to associate with API Gateway. A Kerberos client trying to authenticate to API Gateway must present a TGT containing a matching Kerberos principal name to API Gateway. To select which Kerberos principal to use, click the ... button, and select a previously configured principal from the list. To add a Kerberos principal, right-click Kerberos Principals, and select Add Kerberos Principal. You can also add Kerberos principals under Environment
Configuration > External Connections in the node tree. For more details, see Configure Kerberos principals on page 412. Secret Key
Select this to specify the location of the Kerberos service's secret key that is used to decrypt TGTs received from Kerberos clients. Enter Password:
You can enter a password to generate the Kerberos service's secret key. This key is originally created for a specific principal on the KDC.
Wildcard Password:
##enter stuff here Keytab:
Instead of generating a secret key for the Kerberos service in this configuration dialog, adding the Kerberos service to the KDC usually generates a keytab file containing a mapping between the Kerberos principal name and that principal's secret key. You can load the keytab file to API Gateway configuration using the fields in this section.
To load the principal-to-key mappings into the table in the dialog, select Load Keytab and browse to the existing keytab file. To add a new keytab entry, select Add Principal. To delete a keytab entry, select the entry in the table and click Delete Entry. To export the entire contents of the keytab table in the dialog, click Export Keytab. Note
By default, the contents of the keytab table – derived from a keytab file or manually entered – stored in clear-text form in the underlying configuration data in API Gateway. If necessary, the contents of the keytab table can be encrypted using a passphrase. For more details on encrypting sensitive API Gateway configuration data, see the API Gateway Administrator Guide.
Axway API Gateway 7.5.2
Policy Developer Guide 415
9 External connections
When API Gateway starts, it writes the stored keytab contents to the /conf/plugin/kerberos/keytabs/ directory in your API Gateway installation. It is recommended to configure directory-based or file-based access control for this directory and its contents. For more details on configuring the Keytab Entry dialog, see the Kerberos keytab concepts on page 417.
Load via Native GSS Library:
If you have configured API Gateway to use Native GSS Library on the instance-level Kerberos
Configuration settings, you must choose to load the Kerberos service's secret key from the preferred location. The native GSS library expects the Kerberos service's secret key to be in the default system keytab file. The location of this keytab file is specified in the default_keytab_
name setting in the krb5.conf file that the native GSS library reads using the KRB5_CONFIG environment variable. This keytab can contain keys for multiple Kerberos services.
Advanced settings
Configure the following fields on the Advanced tab:
Mechanism:
Select the mechanism used to establish a context between the Kerberos service and the Kerberos client. The Kerberos client must use the same mechanism. Extract Delegated Credentials:
A Kerberos client can set an attribute on the context established with the Kerberos service to indicate the Kerberos service can act on behalf of the Kerberos client in subsequent communications. This enables a Kerberos service (like API Gateway) to assume the identity of the Kerberos client when communicating with a back-end Kerberos service. The Kerberos client's credentials are propagated to the back-end Kerberos service, not API Gateway's credentials. This is called credential delegation.
If you have configured a Kerberos client to enable delegating its credentials to a Kerberos service, select Extract Delegated Credentials to set the Kerberos service to extract the delegated credentials from the context it establishes with the Kerberos client. The credentials are stored in the gss.delegated.credentials and gss.delegated.credentials.client.name message attributes. To forward the extracted delegated credentials to the back-end Kerberos service on behalf of the Kerberos client, configure the Kerberos settings on the Kerberos Client filter, or use the Connection filter from the Routing category. If using the Connection filter, make sure to select Extract from delegated credentials on the Kerberos Endpoint tab to retrieve the TGT from the extracted delegated credentials for the Kerberos Client on the Kerberos Authentication tab of the Connection filter.
For more details on configuring these options, see the following topics:
l Connection on page 786
l Configure Kerberos clients on page 407
Axway API Gateway 7.5.2
Policy Developer Guide 416
9 External connections
Kerberos keytab concepts
The Kerberos keytab file contains mappings between Kerberos principal names and DES-encrypted keys that are derived from the password used to log into the Kerberos Key Distribution Center (KDC). The purpose of the keytab file is to allow the user to access distinct Kerberos services without being prompted for a password at each service. Furthermore, it allows scripts and daemons to log in to Kerberos services without the need to store clear-text passwords or the need for human intervention. Note
Anyone with read access to the keytab file has full control of all keys contained in the file. For this reason, it is imperative that the keytab file is protected using very strict file-based access control.
Each key entry in the Kerberos keytab file is identified by a Kerberos principal and an encryption type. For this reason, a keytab file can hold multiple keys for the same principal, each key belonging to a different encryption type. If the keytab file contains several keys for a principal, the Kerberos client or service uses the key with the strongest encryption type as agreed during the negotiation of previous messages with the KDC. A keytab file can also contain keys for several different principals. In this case, at runtime, the Kerberos client or service only considers keys mapped to the Kerberos principal name you selected in the Kerberos Principal drop-down list when configuring that Kerberos client or service. The Keytab table in the Secret Key section of the configuration window for a Kerberos client or Kerberos service is essentially a graphical interface to entries in a Kerberos keytab file. To generate a keytab entry, select Keytab > Add Principal. To remove an entry, select the entry and click Delete Entry. You can configure Kerberos clients and services under Environment
Configuration > External Connections in the node tree.
For more details on different Kerberos setups with API Gateway, see API Gateway Kerberos Integration Guide.
Configuration
Configure the following fields on the Keytab Entry dialog:
Kerberos Principal:
Select an existing Kerberos principal from the drop-down list. To add a Kerberos principal, rightclick Kerberos Principals, and select Add Kerberos Principal. You can also add Kerberos principals under Environment Configuration > External Connections in the node tree. For more details, see Configure Kerberos principals on page 412.
Password:
Enter the password to seed the encryption algorithms for the encryption types.
Key version number:
Set the version number for the encryption key.
Axway API Gateway 7.5.2
Policy Developer Guide 417
9 External connections
Encryption Types:
Select the encryption types. The encryption types determine the algorithms used to generate the encryption keys stored in the keytab file. If the keytab file contains multiple keys for a Kerberos principal, the encryption type is used to select an appropriate encryption key.
To ensure maximum interoperability between Kerberos clients and Kerberos services configured in API Gateway and different KDCs, all encryption types are selected by default. This way, the generated keytab entry contains a separate encryption key for each encryption type listed here, and each key is mapped to the selected Kerberos principal name. Note
You must ensure that the required encryption types exist in the keytab as defined in Kerberos system settings in the krb5.conf file. For a Kerberos client to request a Ticket Granting Ticket (TGT), it must have at least one key that matches one of the encryption types listed in the default_tkt_enctypes setting in krb5.conf. A Kerberos service requires a key of a matching encryption type to be able to decrypt a TGT a Kerberos client presents.
For more details on the krb5.conf file, see Kerberos configuration on page 214.
By default, for Windows 2003 Active Directory, TGT is encrypted using the rc4-hmac encryption type. However, if the service user has enabled Use DES encryption types for this account, the des-cbc-md5 encryption type is used.
Configure LDAP directories
Overview
A filter that uses an LDAP directory to authenticate a user or retrieve attributes for a user must have an LDAP directory associated with it. You can use the Configure LDAP Server dialog to configure connection details of the LDAP directory. Both LDAP and LDAPS (LDAP over SSL) are supported.
When a filter that uses an LDAP directory is run for the first time after a server refresh/restart, the server binds to the LDAP directory using the connection details configured on the Configure LDAP
Server dialog. Usually, the connection details include the user name and password of an administrator user who has read access to all users in the LDAP directory for whom you wish to retrieve attributes or authenticate.
General configuration
Configure the following general LDAP connection settings:
Name:
Enter or select a name for the LDAP filter in the drop-down list.
Axway API Gateway 7.5.2
Policy Developer Guide 418
9 External connections
URL:
Enter the URL location of the LDAP directory. The URL is a combination of the protocol (LDAP or LDAPS), the IP address of the host machine, and the port number for the LDAP service. By default, port 389 is reserved for LDAP connections, while port 636 is reserved for LDAPS connections. For example, the following are valid LDAP directory URLs:
ldap://192.168.0.45:389
ldaps://145.123.0.28:636
Cache Timeout:
Specifies the timeout for cached LDAP connections. Any cached connection that is not used in this time period is discarded. Defaults to 300000 milliseconds (5 minutes). A cache timeout of 0 means that the LDAP connection is cached indefinitely and never times out.
Cache Size:
Specifies the number of cached LDAP connections. Defaults to 8 connections. A cache size of 0 means that no caching is performed. Authentication configuration
If the configured LDAP directory requires clients to authenticate to it, you must select the appropriate authentication method in the Authentication Type field. When the API Gateway connects to the LDAP directory, it is authenticated using the selected method. Choose one of the following authentication methods:
l None
l Simple
l Digest-MD5
l External
Note
If any of the following authentication methods connect to the LDAP server over SSL, that server's SSL certificate must be imported into the API Gateway certificate store.
None
No authentication credentials need to be submitted to the LDAP server for this method. In other words, the client connects anonymously to the server. Typically, a client is only allowed to perform read operations when connected anonymously to the LDAP server. It is not necessary to enter any details for this authentication method.
Simple
Simple authentication involves sending a user name and corresponding password in clear text to the LDAP server. Because the password is passed in clear text to the LDAP server, it is recommended to connect to the server over an encrypted channel (for example, over SSL).
Axway API Gateway 7.5.2
Policy Developer Guide 419
9 External connections
It is not necessary to specify a Realm for the Simple authentication method. The realm is only used when a hash of the password is supplied (for Digest-MD5). However, in cases where the LDAP server contains multiple realms, and the specified user name is present in more than one of these realms, it is at the discretion of the specific LDAP server as to which user name binds to it.
Select the SSL Enabled checkbox to force the API Gateway to connect to the LDAP directory over SSL. To successfully establish SSL connections with the LDAP directory, you must import the directory's certificate into the API Gateway's c ertificate store. You can do this using the global Certificates window (see Manage X.509 certificates and keys on page 230). For LDAPS (LDAP over SSL) connections, the LDAP server's certificate must be imported into the Policy Studio JRE trusted store. For more details, see Test the LDAP connection on page 420.
Digest-MD5
With Digest-MD5 authentication, the server generates some data and sends it to the client. The client encrypts this data with its password according to the MD5 algorithm. The LDAP server then uses the client's stored password to decrypt the data and hence authenticate the user.
The Realm field is optional, but may be necessary in cases where the LDAP server contains multiple realms. If a realm is specified, the LDAP server attempts to authenticate the user for the specified realm only.
External
External authentication enables you to use client certificate-based authentication when connecting to an LDAP directory. When this option is selected, you must select a client certificate from the API Gateway certificate store. The SSL Enabled checkbox is selected automatically. Click the Signing
Key button to select the client certificate to use to mutually authenticate to the LDAP server.
Note
This means that you must specify the URL field using LDAPS (for example, ldaps://145.123.0.28:636). The user name, password, and realm fields are not required for external authentication.
Test the LDAP connection
When you have specified all the LDAP connection details, you can click the Test Connection button to verify that the connection to the LDAP directory is configured successfully. This enables you to detect any configuration errors at design time, rather than at runtime. For LDAPS (LDAP over SSL) connections, the LDAP server's certificate must be imported into the Policy Studio JRE trusted store. You can do this by performing the following steps in Policy Studio:
1. Select the Environment Configuration > Certificates and Keys > Certificates node in the Policy Studio tree.
2. In the Certificates panel on the right, click Create/Import, and click Import Certificate.
Axway API Gateway 7.5.2
Policy Developer Guide 420
9 External connections
3. Browse to the LDAP server's certificate file, and click Open.
4. Click Use Subject on the right of the Alias Name field, and click OK. The LDAP server's certificate is now imported into the Certificate Store, and must be added to the Java keystore.
5. In the Certificates panel, select the certificates that you wish the JRE to trust.
6. Click Export to Keystore, and browse to the cacerts file in the following directory:
INSTALL_DIR\policystudio\Win32\jre\lib\security\cacerts
7. Select the cacerts file.
8. Click Save.
9. You are prompted for a password. 10. Click OK.
11. Restart Policy Studio.
12. You can now click Test Connection to test the connection to the LDAP directory server over SSL.
Additional JNDI properties
You can also specify optional JNDI properties as simple name-value pairs. Click the Add button to specify properties in the dialog.
Configure proxy servers
Overview
You can configure settings for individual proxy servers under the Environment Configuration > External Connections node in the Policy Studio tree, which you can then specify at the filter level (in the Connection and Connect To URL filters). When configured, the filter connects to the HTTP proxy server, which in turn routes the message on to the destination server named in the request URI. For more details, see Connection on page 786 and Connect to URL on page 780. These proxy server settings are different from the global proxy settings in the Preferences dialog in the Policy Studio, which apply only when downloading WSDL, XSD, and XSLT files from the Policy Studio. For more details, see Policy Studio preferences on page 190.
Axway API Gateway 7.5.2
Policy Developer Guide 421
9 External connections
Configuration
To configure a proxy server under the Environment Configuration > External Connections tree node, right-click the Proxy Servers node, and select Add a Proxy Server. You can configure the following settings in the dialog:
Proxy Server
Setting
Description
Name
Unique name or alias for these proxy server settings.
Host
Host name or IP address of the proxy server.
Port
Port number on which to connect to the proxy server.
Username
Optional user name when connecting to the proxy server.
Password
Optional password when connecting to the proxy server.
Scheme
Specifies whether the proxy server uses the HTTP or HTTPS transport. Defaults to HTTP.
Configure RADIUS clients
Overview
The API Gateway provides support for integration with remote systems over the Remote Authentication Dial In User Service (RADIUS) protocol. RADIUS is a client-server network protocol that provides centralized authentication and authorization for clients connecting to remote services. For more details, see the RADIUS specification.
To configure a client connection to a remote server over the RADIUS protocol, under the Environment Configuration > External Connections tree node in the Policy Studio, select RADIUS Clients > Add a RADIUS Client. This topic explains how to configure the settings the RADIUS Client dialog. For details on how to configure a RADIUS authentication repository, see Configure authentication repositories on page 377.
Configuration
Configure the following fields in the RADIUS Client dialog:
Axway API Gateway 7.5.2
Policy Developer Guide 422
9 External connections
Name:
Enter an appropriate name for the RADIUS client to display in Policy Studio.
Host name:
Enter the host name used by the RADIUS client.
Client port:
Enter the port number used by the RADIUS client.
RADIUS servers:
This field displays a list of configured RADIUS servers. To add a server to the list, click Add, and complete the following fields:
Name
Name of the RADIUS server.
Port
Port number used by the RADIUS server. Secret
Shared secret used to access the RADIUS server. Response timeout
(sec)
Response timeout in seconds before the connection to the server is closed. Retransmit count
Number of times retransmission is attempted before the connection to the server fails. Configure SiteMinder/SOA Security Manager
connections
This topic explains how to create connections to CA SiteMinder and CA SOA Security Manager. Before you start, you must register API Gateway as an agent in the CA SiteMinder Policy Server. For more details, see API Gateway Authentication and Authorization Integration Guide.
Prerequisites
The following prerequisites apply to SiteMinder/SOA Security Manager connections.
CA SiteMinder connections
Integration with CA SiteMinder requires CA SiteMinder SDK version 12.52-sp02 or later. You must add the required third-party binaries to your API Gateway and Policy Studio installations.
1. Ensure that any SiteMinder binaries you may have previously added to API Gateway have been deleted.
2. Install CA SiteMinder SDK.
Axway API Gateway 7.5.2
Policy Developer Guide 423
9 External connections
3. Copy the following jar files from the java directory of the CA SDK :
l cryptoj.jar
l smagentapi.jar
l smjavasdk2.jar
4. Add the files to the following directory on API Gateway:
l On Windows: INSTALL_DIR\apigateway\ext\lib
l On UNIX/Linux: INSTALL_DIR/apigateway/<platform>/lib
5. Restart API Gateway. CA SOA Security Manager connections
Integration with CA SOA Security Manager requires CA TransactionMinder SDK version 6.0 or later. You must add the required third-party binaries to your API Gateway and Policy Studio installations.
For details on obtaining the required third-party binaries, see your CA product documentation.
Add third-party binaries to API Gateway
To add third-party binaries to API Gateway, perform the following steps:
1. Add the binary files as follows:
l Add .jar files to the INSTALL_DIR/apigateway/ext/lib directory.
l Add .dll files to the INSTALL_DIR\apigateway\Win32\lib directory.
l Add .so files to the INSTALL_DIR/apigateway/<platform>/lib directory.
2. Restart API Gateway.
Add third-party binaries to Policy Studio
To add third-party binaries to Policy Studio, perform the following steps:
1. Select Windows > Preferences > Runtime Dependencies in the Policy Studio main menu.
2. Click Add to select a JAR file to add to the list of dependencies.
3. Click Apply when finished. A copy of the JAR file is added to the plugins directory in your Policy Studio installation.
4. Click OK.
5. Restart Policy Studio with the -clean option. For example:
> cd INSTALL_DIR/policystudio/
> policystudio -clean
Axway API Gateway 7.5.2
Policy Developer Guide 424
9 External connections
Add a new connection
To add a new connection, in the node tree, click Environment Configuration > External
Connections, right-click the SiteMinder/SOA Security Manager Connection node, and select Add a SiteMinder Connection or Add a SOA Security Manager Connection.
To specify how API Gateway connects to SiteMinder, use the SiteMinder Connection Details dialog. To specify how API Gateway connects to CA SOA Security Manager, use the SOA Security
Manager Connection Details dialog. The connection details to be configured are the same for both the SiteMinder and SOA Security Manager, with an additional setting for SOA Security Manager.
SiteMinder and SOA Security Manager
connection settings
This section describes settings that are common to both CA SiteMinder and CA SOA Security Manager connections.
Agent Name:
Enter the name of the agent to connect to SiteMinder or SOA Security Manager in the Agent Name field. This name must correspond to the name of an agent previously configured in the CA SiteMinder Policy Server.
Agent Configuration Object:
The name entered must match the name of the Agent Configuration Object (ACO) configured in the CA SiteMinder Policy Server. The only feature represented by the ACO parameters that API Gateway currently supports is the PersistentIPCheck setting. If you set the PersistentIPCheck ACO parameter to yes, API Gateway compares the IP address from the last request (stored in a persistent cookie) with the IP address in the current request to see if they match. If the IP addresses do not match, API Gateway rejects the request. This check is disabled if you set this parameter to no.
SMHost.conf file created by smreghost:
API Gateway host machine must be registered as an agent with SiteMinder or SOA Security Manager. To register the host, you must use the smreghost tool on API Gateway machine. The tool creates a file called SmHost.conf, which you can then upload into API Gateway configuration using Policy Studio. For more details on creating the SmHost.conf file, see API Gateway Authentication and Authorization Integration Guide
To add the SmHost.conf file to API Gateway, ensure the SmHost.conf file is copied to the same machine running Policy Studio, click Browse, and select the the SmHost.conf file. You can select whether to use an SmHost.conf or SmHost.cnf file in the dialog. You can also enter the file name as an environment variable selector (for example, ${env.SMHOST}). For more details, see the API Gateway DevOps Deployment Guide.
After selecting the SmHost.conf configuration file, you can see the connection details in the text area.
Axway API Gateway 7.5.2
Policy Developer Guide 425
9 External connections
SOA Security Manager connection settings
This section describes details that are specific to CA SOA Security Manager connections only. In addition to the fields already described in the previous section, you must also configure the following field on the SOA Security Manager Connection Details dialog.
XMLSDKAcceptSMSessionCookie:
This setting controls whether the CA SOA Security Manager authentication filter accepts a single sign-on token for authentication purposes. The single sign-on token must reside in the HTTP header field named SMSESSION to authenticate using this mechanism. This token is created and updated when the CA SOA Security Manager authorization filter runs successfully.
When this check box is selected, the authentication filter allows authentication using a single signon token.
Note
If no single sign-on token is present in the message, the authentication filter authenticates fully by gathering credentials from the request in whatever manner has been configured in the CA SOA Security Manager. When this check box is unselected, the authentication filter authenticates fully (it never allows authentication using a single sign-on token).
Configure SMTP servers
Overview
You can configure the API Gateway to use a specified Simple Mail Transfer Protocol (SMTP) server to relay messages to an email recipient. You can configure the SMTP server as a global configuration item under the Environment Configuration > External Connections node. The SMTP server is then available for selection in the SMTP filter in the Routing category.
To configure an SMTP server, right-click the Environment Configuration > External
Connections > SMTP Servers node, and select Add an SMTP Server. Alternatively, in the SMTP filter window, click the button beside the SMTP Server Settings field, right-click the SMTP Servers node, and select Add an SMTP Server.
Configuration
Configure the following fields in the SMTP Server settings dialog:
Name:
Enter an appropriate name for the SMTP server.
SMTP Server Settings
Specify the following fields:
l SMTP Server Hostname:
Enter the host name or IP address of the SMTP server.
Axway API Gateway 7.5.2
Policy Developer Guide 426
9 External connections
l Port:
Enter the SMTP port on the specified server hostname. By default, SMTP servers run on port 25.
l Connection Security:
Select the security required for the connection to the SMTP server ( SSL, TLS, or NONE). Defaults to NONE.
Log on using
If you are required to authenticate to the SMTP server, specify the following fields:
l User Name:
Enter the user name of a registered user that can access the SMTP server. l Password:
Enter the password for the user name specified.
Note
The SMTP server connection supports a simple user name and password type of authentication. Microsoft Windows NT LAN Manager (NTLM) authentication is not supported.
Configure trusted certificates for
SMTP connections
SMTP server connections use a Java keystore instead of the API Gateway certificate store. You must import the certificate chain into the following file: <install-dir>\apigateway\<platform>\jre\lib\security\cacerts
The default password is changeit.
Configure TIBCO Rendezvous daemons
Overview
TIBCO Rendezvous is a low latency messaging product for real-time high throughput data distribution applications. A message can be sent from the TIBCO daemon running on the local machine to a single TIBCO daemon running on a separate host machine or it can be broadcast to several daemons running on multiple machines. Each message has a subject associated with it, which acts as the destination of the message. A listener, which is itself a TIBCO daemon, can declare an interest in a subject on a specific daemon. Whenever a message is delivered to this subject on the daemon the message is delivered to the listening daemon. Axway API Gateway 7.5.2
Policy Developer Guide 427
9 External connections
The API Gateway can act as a listener on a specific subject at a TIBCO daemon, in which case it said to be acting as a consumer of TIBCO messages. Similarly, it can also send messages to a TIBCO daemon, effectively acting as a producer of messages. In both cases, the local TIBCO daemon must be configured to talk to the TIBCO daemons running on the remote machines. For more information on consuming and producing messages to and from TIBCO Rendezvous, see the following topics:
l TIBCO integration on page 362
l TIBCO Rendezvous listener on page 362
l Route to TIBCO Rendezvous on page 801
The remainder of this topic describes how to configure a TIBCO Rendezvous daemon. For a more detailed description of how to configure the fields on this dialog, refer to your TIBCO Rendezvous documentation. Configuration
You can configure TIBCO Rendezvous daemons under the Environment Configuration > External Connections tree node in the Policy Studio. Right-click the TIBCO Rendezvous
Daemons node, and select Add a TIBCO Rendezvous Daemon. Configure the following fields on the TIBCO Daemon Settings dialog:
Name:
Enter a friendly name for this TIBCO Rendezvous daemon. When configured, this name is available for selection when configuring a TIBCO Rendezvous Listener and a TIBCO Rendezvous filter.
Service:
Communication between TIBCO Rendezvous daemons takes place using Pragmatic General Multicast (PGM) or Universal Datagram Protocol (UDP) services. The specified service parameter configures the local TIBCO Rendezvous daemon to use this type of service when sending or broadcasting messages to other TIBCO Rendezvous daemons who are also using this service.
You can specify the service in the following ways:
l By Service Name:
If your network administrator has added an entry for TIBCO Rendezvous in a network database such as NIS (for example, rendezvous 7500/udp), you can enter the name of the service (for example, rendezvous) in this field.
l By Port Number:
Alternatively, you can enter the port number on which the TIBCO Rendezvous daemon is listening (for example, 7500).
l Default Option:
If you leave this field blank, a default service name of rendezvous is assumed. For this reason, administrators should add an entry in the network database with this name (for example, rendezvous 7500/udp. This enables you to leave this field blank so that this default service is used. Axway API Gateway 7.5.2
Policy Developer Guide 428
9 External connections
Network:
If the machine on which the TIBCO Rendezvous daemon is running has more than one network interface, you can specify what interface to use for all communications with other daemons. Each TIBCO Rendezvous daemon can only communicate on a single network, meaning that separate daemons must be configured for each network you want the daemon to communicate on. For simplicity, you can leave this field blank, in which case the primary network interface is used for communication with other daemons. For more information on how to configure different networks and multicast groups, see the TIBCO Rendezvous documentation.
Daemon:
The value entered here tells the API Gateway where it can find the TIBCO Rendezvous daemon, which is responsible for communicating with all other daemons on the network. This daemon can be local or remote.
For local daemons you need only specify the port number that the daemon is running on (for example 6500). Alternatively, you can leave this field blank to connect to the daemon on the default port. To connect to a remote daemon, you must specify both the host and port number of the daemon in this field (for example daemon_host:6500).
Configure Tivoli connections
Tivoli Access Manager for e-business is a commonly used product for securing web resources. Tivoli message filters allows the API Gateway to leverage existing Access Manager policies, thus avoiding the need to maintain duplicate policies in both products. At runtime, the Tivoli filters can delegate authentication and authorization decisions to Access Manager, and can also retrieve user attributes.
Tivoli connections determine how a particular API Gateway instance connects to an instance of a Tivoli server. Note
Each API Gateway instance can connect to a single Tivoli server. Prerequisites
Before you can configure the Tivoli Authorization filter, you must configure API Gateway for integration with TAM. For more details, see API Gateway Authentication and Authorization Integration Guide
Configuration
To configure Tivoli connection, in the node tree, select Environment Configuration > Server
Settings > Security > Tivoli. Alternatively, you can a click Environment Configuration >
External Connections > Tivoli Connection, and select Add a Tivoli Connection. The newly added connection can then be assigned to a particular API Gateway instance.
Axway API Gateway 7.5.2
Policy Developer Guide 429
9 External connections
In both cases, the Tivoli Configuration dialog is used to add the connection details required for the API Gateway to connect to the Tivoli server. The connection details are stored in the Tivoli configuration files. This dialog allows you to upload these files to the API Gateway.
Configure the following fields on the Tivoli Configuration dialog:
Name:
Enter a name onfor the connection, or select a previously configured Tivoli connection on which to base the new configuration.
Select configuration file specification method:
You can specify how to upload the Tivoli configurations files:
l Upload Tivoli configuration files: You can automatically upload all configuration files to a specified API Gateway instance. API Gateway overwrites these files each time at startup or refresh (for example, when configuration updates are deployed). This means that any changes to the main configuration file must be made using the Policy Studio and not directly to the file on disk.
l Set file location for main Tivoli Configuration file: You can manually copy the configuration files to the file system of a API Gateway instance and point API Gateway to pick up the configuration files from that location. API Gateway does not overwrite the files at startup or refresh time. You can edit the main configuration file directly using an editor of your choice.
Connection enabled:
Select to immediately enable the connection, deselect to disable the connection. You can edit this selection later to disable or enable the connection as needed by toggling this check box.
Tivoli configuration files:
If you selected to upload the Tivoli configuration files, use the use the Load File and Next buttons in the Upload Tivoli configuration files windows to upload all configuration files to the specified API Gateway instance. The files are displayed in the text area, and depending on the file, you may be able to edit the contents of the file.
Server-side Tivoli configuration file: Set the location of the main Tivoli configuration file.
Configure XKMS connections
Overview
XML Key Management Specification (XKMS) is an XML-based protocol that enables you to establish the trustworthiness of a certificate over the Internet. The API Gateway can query an XKMS responder to determine whether a given certificate can be trusted.
You can add XKMS Connections under the Environment Configuration > External
Connections tree node in Policy Studio. To add a global XKMS Connection, right-click the XKMS
Connections node, and select Add an XKMS Connection. Axway API Gateway 7.5.2
Policy Developer Guide 430
9 External connections
Configuration
Configure the following fields on the Certificate Validation - XKMS window.
Name:
Enter an appropriate name for this XKMS connection.
URL Group:
Select a group of XKMS responders from the URL Group list. The API Gateway attempts to connect to the XKMS responders in the selected group in a round-robin fashion. It attempts to connect to the responders with the highest priority first, before connecting to responders with a lower priority. You can add, edit, or remove URL Groups by selecting the appropriate button. For more information on adding and editing URL groups, see Configure URL groups on page 876. User Name:
Requests to XKMS responders can be signed by a user to whom the Sign OCSP or XKMS
Requests privilege has been assigned. Only those users who have been assigned this privilege are displayed in the drop-down list. For more information on assigning privileges to users, see Manage API Gateway users on page 243.
Signing Key:
Click the Signing Key button to open the list of certificates in the Certificate Store. You can then select the key to use to sign requests to XKMS responders. This user must have been granted the Sign OCSP or XKMS Requests privilege.
Axway API Gateway 7.5.2
Policy Developer Guide 431
Amazon Web Services
filters
10
The following filters enable you to integrate with Amazon Web Services:
Send to Amazon SQS
432
Upload to Amazon S3
434
Send to Amazon SQS
Overview
Amazon Simple Queue Service (SQS) is a hosted message queuing service for distributing messages amongst machines. API Gateway acts as a client to SQS and can send messages to SQS. You can use the Send to Amazon SQS filter to send messages to an SQS queue.
For more information on Amazon SQS, go to http://aws.amazon.com/sqs/. General settings
Configure the following settings on the Send to Amazon SQS window:
Name:
Enter a suitable name for the filter to display in a policy.
AWS settings
AWS Credential:
Click the browse button to select your AWS security credentials (API key and secret) for Amazon SQS.
Region:
Select the region in which to access the SQS service. You can choose from the following options:
l US East (Northern Virginia)
l US West (Oregon)
l US West (Northern California)
Axway API Gateway 7.5.2
Policy Developer Guide 432
10 Amazon Web Services filters
l EU (Ireland)
l Asia Pacific (Singapore)
l Asia Pacific (Tokyo)
l Asia Pacific (Sydney)
l South America (Sao Paulo)
l US GovCloud
Client settings:
Click the browse button to select the AWS client configuration to be used by API Gateway when connecting to Amazon SQS. For more information on configuring client settings, see Configure AWS client settings on page 365.
Send message settings
Configure the following settings on the Send Message tab:
Queue name:
Enter the name of the queue to send the message to. The default name is publishQueue. To create a new queue with the specified name, click the Create option.
Send the message payload:
Select this option to send the message payload to the queue.
Or send the value of the attribute below to SQS:
Select this option to send the value of an attribute to the queue. Complete the following fields:
l Attribute Name:
Enter the name of the attribute.
l Content Type:
Enter the content type to be used for sending the message to SQS (for example, text/plain).
l Content Encoding:
Enter the content encoding.
Advanced settings
On the Advanced tab you can configure how to handle messages that are larger than 256KB in size. Configure these fields:
Split message into smaller ones:
Select this option to split the message into smaller messages before sending it to the queue.
Store in S3 and place pointer on SQS queue:
Select this option to store the payload in Amazon S3 and place a pointer to S3 in the queue. Configure the S3 settings as described in S3 settings on page 435.
Axway API Gateway 7.5.2
Policy Developer Guide 433
10 Amazon Web Services filters
Further information
For more detailed information on Amazon Web Services integration, see the AWS Integration Guide available from Axway Support.
Upload to Amazon S3
Overview
Amazon Simple Storage Service (S3) is an online storage web service that you can use to store and retrieve any amount of data. API Gateway acts as a client to S3 and can upload data to S3. You can use the Upload to Amazon S3 filter to upload data to Amazon S3.
For more information on Amazon S3, go to http://aws.amazon.com/s3/. General settings
Configure the following settings on the Upload to Amazon S3 window:
Name:
Enter a suitable name for the filter to display in a policy.
AWS settings
AWS Credential:
Click the browse button to select your AWS security credentials (API key and secret) for Amazon S3.
Region:
Select the region in which to store your data. You can choose from the following options:
l US East (Northern Virginia)
l US West (Oregon)
l US West (Northern California)
l EU (Ireland)
l Asia Pacific (Singapore)
l Asia Pacific (Tokyo)
l Asia Pacific (Sydney)
l South America (Sao Paulo)
l US GovCloud
Axway API Gateway 7.5.2
Policy Developer Guide 434
10 Amazon Web Services filters
Client settings:
Click the browse button to select the AWS client configuration to be used by API Gateway when connecting to Amazon S3. For more information on configuring client settings, see Configure AWS client settings on page 365.
S3 settings
Bucket name:
Enter the name of the bucket in which to store the data. To create a new bucket with the specified name, click the Create option.
Object key:
Enter the object key for the object to be stored. Alternatively, you can enter a selector that is expanded at runtime. For more details on selectors, see Select configuration values at runtime on page 854.
Encryption key:
Click the browse button to select an encryption key for the object.
How to store:
Select how to store the object. You can choose from the following options:
l Standard – This is the standard S3 storage option.
l Reduced Redundancy – This is a storage option within Amazon S3 for storing non-critical, reproducible data at lower levels of redundancy than standard storage.
l Glacier – This is a low-cost storage o ption for data archival.
Further information
For more detailed information on Amazon Web Services integration, see the AWS Integration Guide available from Axway Support.
Axway API Gateway 7.5.2
Policy Developer Guide 435
Attribute filters
11
The following filters enable you to work with message attributes:
Compare attribute
436
Extract REST request attributes
438
Extract WSS header
440
Extract WSS timestamp
441
Extract WSS UsernameToken element
441
Get cookie
442
Insert SAML attribute assertion
443
Retrieve attributes from JSON message
451
Retrieve attribute from directory server
454
Retrieve attribute from HTTP header
458
Retrieve attribute from SAML attribute assertion
459
Retrieve attribute from SAML PDP
462
Retrieve attribute from Tivoli
465
Retrieve attribute from message
466
Retrieve attribute from database
467
Retrieve attribute from user store
470
Compare attribute
Overview
The Compare Attribute filter enables you to compare the value of a specified message attribute on the API Gateway white board with the values specified in the filter. For example, the following filter only passes if the ${authentication.subject.id} message attribute has a value of penelope:
Axway API Gateway 7.5.2
Policy Developer Guide 436
11 Attribute filters
Configuration
Configure the following fields:
Name:
Enter an appropriate name for this filter to display in a policy.
Filter will pass if:
Select all or one of the specified conditions to apply. Defaults to all. Click the Add button at the bottom right to specify a rule condition. In the Attribute filter rule dialog, perform the following steps:
1. Enter a message attribute selector in the Value from text box on the left (for example, ${http.request.verb} or ${my.customer.attribute}).
2. Select one of the following rule conditions from the list:
l contains
l doesn't contain
l doesn't match regular expression
l ends with
l is
l is not
l matches regular expression
l starts with
3. Enter a value to compare with in the text box on the right (for example, POST). Alternatively, you can enter a selector that is expanded at runtime (for example, ${http.request.uri}). For more details on selectors, see Select configuration values at runtime on page 854.
4. Click OK.
Finally, to edit or delete an existing rule condition, select it in the table, and click the appropriate button.
Axway API Gateway 7.5.2
Policy Developer Guide 437
11 Attribute filters
Extract REST request attributes
Overview
This filter extracts the values of query string parameters and HTTP headers from a REST request and stores them in separate message attributes. The request can be an HTTP GET or HTTP POST request. This filter is in the Attributes category in Policy Studio. For details on creating a REST request, see Create REST request on page 641.
HTTP GET requests
The following example shows an incoming HTTP GET request with query string and HTTP headers:
GET /services?name=Niall&location=Dublin&location=Pembroke%20St HTTP/1.1
Host:mail.google.com
User-Agent:Mozilla/5.0 (Windows; U; Windows NT 6.1; en-GB; rv:1.9.2.15)
Gecko/20110303 Firefox/3.6.15
Accept:text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language:en-gb,en;q=0.5
Accept-Encoding:gzip,deflate
Accept-Charset:ISO-8859-1,utf-8;q=0.7,*;q=0.7
Using this example, when Request Querystring is selected, the Extract REST Request
Attributes filter generates the following attributes:
http.header.Host = mail.google.com
http.header.User-Agent = Mozilla/5.0 (Windows; U; Windows NT 6.1; en-GB;
rv:1.9.2.15)
Gecko/20110303 Firefox/3.6.15
http.header.Accept = text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
http.header.Accept-Language = en-gb,en;q=0.5
http.header.Accept-Encoding = gzip,deflate
http.header.Accept-Charset = ISO-8859-1,utf-8;q=0.7,*;q=0.7
params.query.name = Niall
params.query.location.1 = Dublin
params.query.location.2 = Pembroke St
This filter extracts all parameters from an incoming REST request, and stores them in separate message attributes so that they can be validated easily.
Note
For multi-valued query string parameters, each value is given an incremental index. For example, the multi-valued location parameter results in the creation of the params.query.location.1 and params.query.location.2 message attributes. Axway API Gateway 7.5.2
Policy Developer Guide 438
11 Attribute filters
HTTP POST requests
When you POST a form to the API Gateway, the parameters are placed in the message body, and not in the query string. However, the Extract REST Request Attributes filter treats posted parameters the same as normal query parameters, and also adds them to the params.query message attribute in a similar way to the HTTP GET request. For example, an HTTP POST message body contains the following:
grant_type=password&username=johndoe&password=A3ddj3w
This means that the ${params.query.grant_type} message attribute selector contains a value of password.
Configuration
Configure the following fields on the Extract REST Request Attributes window:
Name:
Enter an appropriate name for this filter to display in a policy.
Request Querystring:
Select whether to extract the values of query string parameters from an HTTP POST or GET request. These are simple name-value pairs (for example, Name=Joe Bloggs). This setting is selected by default.HTTP Headers:
Select whether to extract the HTTP header values from an HTTP POST or GET request (selected by default).
Decode Extracted Attributes:
Select whether to decode URI paths that have been percent-encoded (for example, using %2F for /). This setting enables compatibility with previous API Gateway versions, which decoded URI paths, and is not selected by default. For example, this means that URI path components such as the following stay in a raw state:
/s8koID4%2FAd6AqgADSghC%2Bg%3D%3D/book%20repo/first%20book.pdf
This results in:
path[0]
path[1]
path[2]
path[3]
=
=
=
=
""
"s8koID4%2FAd6AqgADSghC%2Bg%3D%3D"
"book%20repo"
"first%20book.pdf"
When this setting is selected, the URI path is decoded. This results in:
path[0] = ""
path[1] = "s8koID4%/Ad6AqgADSghC+g=="
Axway API Gateway 7.5.2
Policy Developer Guide 439
11 Attribute filters
path[2] = "book repo"
path[3] = "first book.pdf"
Extract WSS header
Overview
The Extract WSS Header filter extracts a WS-Security Header block from a message. The extracted security header is stored in the authentication.ws.wsblockinfo message attribute.
To process this security header later in the policy, you can specify this message attribute in the configuration window for the specific processing filter. For example, to sign the security header, you can specify the authentication.ws.wsblockinfo message attribute in the What to
Sign section of the XML Signature Generation filter. Open the Message Attribute tab on the What to Sign window, and specify this attribute to sign the security header. Timestamp validity
The Extract WSS Header filter implicitly checks the wsu:Timestamp in the WSS Header block, if present. It checks the Expires and Created time to determine whether the current time is between the following values:
[Created time - drift time], [Expires time + drift time]
The drift time is taken from the value set in Environment Configuration > Server Settings >
General > Token drift time (secs), which defaults to 300 seconds. This filter fails if the extracted WSS header block contains an invalid timestamp.
Configuration
Configure the following fields on the Extract WSS Header filter configuration window:
Name:
Enter an intuitive name for this filter to display in a policy (for example, ExtractCurrent
Actor WSS Header). Actor or Role:
Specify the name of the SOAP Actor or Role of the WS-Security header that you want to extract. Remember, the WS-Security header is stored in the authentication.ws.wsblockinfo message attribute.
Axway API Gateway 7.5.2
Policy Developer Guide 440
11 Attribute filters
Remove enclosing WS-Security element:
This option removes the enclosing wsse:Security element from the message.
Extract WSS timestamp
Overview
You can use the Extract WSS Timestamp filter to extract a WSS header timestamp from a message. The timestamp is stored in a specified message attribute so that it can be processed later in a policy. This filter requires the WSS header block to have been extracted previously. For more details, see Extract WSS header on page 440.
Typically, the Validate Timestamp filter is used to retrieve the timestamp from the specified message attribute and validate it. The Validate Timestamp filter is available from the Content
Filtering filter category. For more details, see Validate timestamp on page 630.
Configuration
Configure the following fields on the Extract WSS Timestamp filter configuration window:
Name:
Enter an appropriate name for this filter to display in a policy.
Message Attribute to Contain the Timestamp:
When API Gateway extracts the WSS header timestamp from the message at runtime, it stores the timestamp in the specified message attribute. To validate the timestamp later in the policy, you must
specify this message attribute in the configuration window for the Validate Timestamp filter. Extract WSS UsernameToken element
Overview
You can use the Extract WSS Username Token filter to extract a WS-Security UsernameToken from a message if it exists. The extracted UsernameToken token is stored in the wss.usernameToken message attribute.
To process the UsernameToken later in the policy, you can specify this message attribute in the configuration window for the processing filter. For example, to sign the UsernameToken, you can simply specify the wss.usernameToken message attribute in the What to Sign section of the XML Signature Generation filter. Open the Message Attribute tab on the What to Sign window, and specify this attribute to sign the user name token. Axway API Gateway 7.5.2
Policy Developer Guide 441
11 Attribute filters
Configuration
Configure the following field on the Extract WSS Username Token filter configuration window:
Name:
Enter an appropriate name for the filter. Remember that the WS-Security UsernameToken is stored in the wss.usernameToken message attribute.
Get cookie
Overview
An HTTP cookie is data sent by a server in an HTTP response to a client. The client can then return an updated cookie value in subsequent requests to the server. For example, this enables the server to store user preferences, manage sessions, track browsing habits, and so on. The Get Cookie filter is used to read the Cookie and Set-Cookie HTTP headers. The Cookie header is used when a client sends a cookie to a server. The Set-Cookie header is used when the server instructs the client to store a cookie. For more details, see Create cookie on page 640.
Configuration
Configure the following fields on the Get Cookie filter configuration window:
Filter Name:
Enter an appropriate name for this filter to display in a policy..
Cookie Name:
Enter a regular expression that matches the name of the cookie. This value can use wildcards. Defaults to the.* wildcard. Remove all Cookie Headers from Message after retrieval:
When this setting is selected, all Cookie and Set-Cookie headers are removed from the message after retrieving the target cookie. This setting is not selected by default.
Attribute storage
When a cookie is retrieved, it is stored in the appropriate API Gateway message attribute. The following message attributes are used to store cookies:
Axway API Gateway 7.5.2
Policy Developer Guide 442
11 Attribute filters
Cookie Header
Type
Message Attribute Name
Cookie
cookie.cookie_name.value (for example, cookie.mytest.value)
cookie.cookie_name.cookie_attribute_name (for example, Set-Cookie
cookie.mytest.header)
Set-Cookie attribute list
The Set-Cookie HTTP header includes the following cookie attributes (reflected in the SetCookie message attribute name):
Cookie
Attribute
Name
Description
header
The HTTP header name.
value
The value of the cookie.
domain
The domain name for this cookie.
path
The path on the server to which the browser returns this cookie.
maxage
The maximum age of the cookie in days, hours, minutes, and/or seconds.
secure
Whether sending this cookie is restricted to a secure protocol. This setting is not selected by default, which means that it can be sent using any protocol. HTTPOnly
Whether the browser should use cookies over HTTP only. This setting is not selected by default.
Insert SAML attribute assertion
Overview
A Security Assertion Markup Language (SAML) attribute assertion contains information about a user in the form of a series of attributes. Having collated a certain amount of information about a user, the API Gateway can generate a SAML attribute assertion, and insert it into the downstream Axway API Gateway 7.5.2
Policy Developer Guide 443
11 Attribute filters
message.
A SAML Attribute (see example below) is generated for each entry in the attribute.lookup.list attribute. Other filters from the Attributes filter group can be used to insert user attributes into the attribute.lookup.list attribute.
You can refer to the following example of a SAML attribute assertion when configuring this filter:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
<soap:Header>
<wsse:Security>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
ID="Id-0000010a3c4ff12c-0000000000000002"
IssueInstant="2006-03-27T15:26:12Z" Version="2.0">
<saml:Issuer Format="urn:oasis ... WindowsDomainQualifiedName">
TestCA
</saml:Issuer>
<saml:Subject>
<saml:NameIdentifier Format="urn:oasis ... WindowsDomainQualifiedName">
TestUser
</saml:NameIdentifier>
</saml:Subject>
<saml:Conditions NotBefore="2005-03-27T15:20:40Z"
NotOnOrAfter="2028-03-27T17:20:40Z"/>
<saml:AttributeStatement>
<saml:Attribute Name="role" NameFormat="http://www.axway.com">
<saml:AttributeValue>admin</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="email" NameFormat="http://www.axway.com">
<saml:AttributeValue>[email protected]</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="dept" NameFormat="">
<saml:AttributeValue>engineering</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</wsse:Security>
</soap:Header>
<soap:Body>
<product>
<name>API Gateway</name>
<company>Axway</company>
<description>Web Services Security</description>
</product>
</soap:Body>
</soap:Envelope>
Axway API Gateway 7.5.2
Policy Developer Guide 444
11 Attribute filters
Assertion details settings
Configure the following fields on the Assertion Details tab:
Issuer Name:
Select the certificate containing the Distinguished Name (DName) to be used as the Issuer of the SAML assertion. This DName is included in the SAML assertion as the value of the Issuer attribute of the <saml:Assertion> element. For an example, see the sample SAML assertion above. Expire In:
Specify the lifetime of the assertion in this field. The lifetime of the assertion lasts from the time of insertion until the specified amount of time has elapsed.
Drift Time:
The drift time is used to account for differences in the clock times of the machine hosting API Gateway (that generate the assertion) and the machines that consume the assertion. The specified time is subtracted from the time at which API Gateway generates the assertion. SAML Version:
You can create SAML 1.0, 1.1, and 2.0 attribute assertions. Select the appropriate version from the list.
Note
SAML 1.0 recommends the use of the http://www.w3.org/TR/2001/REC-xmlc14n-20010315 XML Signature Canonicalization algorithm. When inserting signed SAML 1.0 assertions into XML documents, it is quite likely that subsequent signature verification of these assertions might fail. This is due to the side effect of the algorithm including inherited namespaces into canonical XML calculations of the inserted SAML assertion that were not present when the assertion was generated.
For this reason, Axway recommend that SAML 1.1 or 2.0 is used when signing assertions as they both uses the exclusive canonical algorithm http://www.w3.org/2001/10/xml-exc-c14n# , which safeguards inserted assertions from such changes of context in the XML document. See section 5.4.2 of the oasis-sstc-saml-core-1.0.pdf and section 5.4.2 of sstc-saml-core1.1.pdf documents, both of which are available at http://www.oasis-open.org.
Assertion location settings
The options on the Assertion Location tab specify where the SAML assertion is inserted in the message. By default, the SAML assertion is added to the WS-Security block with the current SOAP actor/role. The following options are available:
Append to Root or SOAP Header:
Appends the SAML assertion to the message root for a non-SOAP XML message, or to the SOAP Header for a SOAP message. For example, this option is suitable for cases where this filter might process SOAP XML messages or non-SOAP XML messages.
Axway API Gateway 7.5.2
Policy Developer Guide 445
11 Attribute filters
Add to WS-Security Block with SOAP Actor/Role:
Adds the SAML assertion to the WS-Security block with the specified SOAP actor (SOAP 1.0) or role (SOAP 1.1). By default, the assertion is added with the current SOAP actor/role only, which means the WS-Security block with no actor. You can select a specific SOAP actor/role when available from the list.
XPath Location:
To insert the SAML assertion at an arbitrary location in the message, you can use an XPath expression to specify the exact location in the message. You can select XPath expressions from the list. The default is the First WSSE Security Element, which has an XPath expression of //wsse:Security. You can add, edit, or remove expressions by clicking the relevant button. For more details, see Configure XPath expressions on page 877. You can specify exactly how the SAML assertion is inserted using the following options:
l Append to node returned by XPath expression (the default)
l Insert before node returned by XPath expression
l Replace node returned by XPath expression
Insert into Message Attribute:
Specify a message attribute to store the SAML assertion from the drop-down list (for example, saml.assertion). Alternatively, you can also enter a custom message attribute in this field (for example, my.test.assertion). The SAML assertion can then be accessed downstream in the policy. Subject confirmation method settings
The settings on the Subject Confirmation Method tab determine how the <SubjectConfirmation> block of the SAML assertion is generated. When the assertion is consumed by a downstream web service, the information contained in the <SubjectConfirmation> block can be used to authenticate either the end user that authenticated to the API Gateway, or the issuer of the assertion, depending on what is configured.
The following is a typical <SubjectConfirmation> block:
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>
urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
</saml:ConfirmationMethod>
<dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
<dsig:X509Data>
<dsig:X509SubjectName>CN=axway</dsig:X509SubjectName>
<dsig:X509Certificate>
MIICmzCCAY ...... mB9CJEw4Q=
</dsig:X509Certificate>
</dsig:X509Data>
</dsig:KeyInfo>
</saml:SubjectConfirmation>
Axway API Gateway 7.5.2
Policy Developer Guide 446
11 Attribute filters
The following configuration fields are available on the Subject Confirmation Method tab:
Method:
The value selected here determines the value of the <ConfirmationMethod> element. The following table shows the available methods, their meanings, and their respective values in the <ConfirmationMethod> element:
Method
Meaning
Value
Holder Of Key
The API Gateway includes the key used to prove that the API Gateway is the holder of the key, or includes a reference to the key.
urn:oasis:names:tc:SAML:1.0:cm:
holder-of-key
Bearer
The subject of the assertion is the bearer of the assertion.
urn:oasis:names:tc:SAML:1.0:cm:bearer
SAML Artifact
The subject of the assertion is the user that presented a SAML Artifact to the API Gateway.
urn:oasis:names:tc:SAML:1.0:cm:
artifact
Sender Use this confirmation urn:oasis:names:tc:SAML:1.0:cm:bearer
Vouches
method to assert that the API Gateway is acting on behalf of the authenticated end user. No other information relating to the context of the assertion is sent. It is recommended that both the assertion and the SOAP Body must be signed if this option is selected. These message parts can be signed by using the XML
Signature Generation filter (see XML signature generation on page 720).
Note
You can also leave the Method field blank, in which case no <ConfirmationMethod> block is inserted into the assertion.
Axway API Gateway 7.5.2
Policy Developer Guide 447
11 Attribute filters
Holder-of-Key Configuration:
When you select Holder of Key as the SAML subject confirmation in the Method field, you must configure how information about the key is to be included in the message. There are a number of configuration options available depending on whether the key is a symmetric or asymmetric key.
Asymmetric Key:
To use an asymmetric key as proof that the API Gateway is the holder-of-key entity, you must select the Asymmetric Key radio button, and then configure the following fields on the Asymmetric tab:
l Certificate from Store:
To select a key that is stored in the Certificate Store, select this option and click the Signing
Key button. On the Select Certificate screen, select the box next to the certificate that is associated with the key to use. l Certificate from Selector Expression:
Alternatively, the key may have already been used by a previous filter in the policy (for example, to sign a part of the message). In this case, the key can be retrieved using the selector expression entered in this field. Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, Key Property Store, or environment variable). For more details, see Select configuration values at runtime on page 854.
Symmetric Key:
To use a symmetric key as proof that the API Gateway is the holder of key, select the Symmetric
Key radio button, and configure the fields on the Symmetric tab:
l Generate Symmetric Key, and Save in Message Attribute:
If you select this option, the API Gateway generates a symmetric key, which is included in the message before it is sent to the client. By default, the key is saved in the symmetric.key message attribute. l Symmetric Key Selector Expression:
If a previous filter (for example, an XML Signature Generation filter) has already used a symmetric key, you can reuse this key as proof that the API Gateway is the holder-of-key entity. Enter the name of the selector expression (for example, message attribute) in the field provided, which defaults to ${symmetric.key}. Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, Key Property Store, or environment variable). For more details, see Select configuration values at runtime on page 854.
l Encrypt using Certificate from Certificate Store:
When a symmetric key is used, you must assume that the recipient has no prior knowledge of this key. It must, therefore, be included in the message so that the recipient can validate the key. To avoid meet-in-the-middle style attacks, where a hacker could eavesdrop on the communication channel between the API Gateway and the recipient and gain access to the symmetric key, the key must be encrypted so that only the recipient can decrypt the key. One way of doing this is to select the recipient's certificate from the Certificate Store. By encrypting the symmetric key with the public in the recipient's certificate, the key can only be decrypted by the recipient's private key, to which only the recipient has access. Select the Signing Key button and then select the recipient's certificate on the Select Certificate dialog.
Axway API Gateway 7.5.2
Policy Developer Guide 448
11 Attribute filters
l Encrypt using Certificate from Selector Expression:
Alternatively, if the recipient's certificate has already been used (perhaps to encrypt part of the message), the certificate can be retrieved using the selector expression entered in this field. Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, Key Property Store, or environment variable). For more details, see Select configuration values at runtime on page 854.
l Symmetric Key Length:
Enter the length (in bits) of the symmetric key to use.
l Key Wrap Algorithm:
Select the algorithm to use to encrypt ( wrap ) the symmetric key.
Key Info:
The Key Info tab must be configured regardless of whether you have elected to use symmetric or asymmetric keys. It determines how the key is included in the message. The following options are available:
l Do Not Include Key Info:
Select this option if you do not wish to include a <KeyInfo> section in the SAML assertion.
l Embed Public Key Information:
If this option is selected, details about the key are included in a <KeyInfo> block in the message. You can include the full certificate, expand the public key, include the distinguished name, and include a key name in the <KeyInfo> block by selecting the appropriate boxes. When selecting the Include Key Name field, you must enter a name in the Value field, and select the Text Value or Distinguished Name Attribute radio button, depending on the source of the key name. l Put Certificate in Attachment:
Select this option to add the certificate as an attachment to the message. The certificate is then referenced from the <KeyInfo> block. l Security Token Reference:
The Security Token Reference (STR) provides a way to refer to a key contained in a SOAP message from another part of the message. It is often used in cases where different security blocks in a message use the same key material, and it is considered an overhead to include the key more than once in the message. When this option is selected, a <wsse:SecurityTokenReference> element is inserted into the <KeyInfo> block. It references the key material using a URI to point to the key material and a ValueType attribute to indicate the type of reference used. For example, if the STR refers to an encrypted key, you should select EncryptedKey from the list, whereas if it refers to a BinarySecurityToken , select X509v3 from the list. Other options are available to enable more specific security requirements.
Advanced settings
The settings on the Advanced tab include the following fields.
Axway API Gateway 7.5.2
Policy Developer Guide 449
11 Attribute filters
Select Required Layout Type:
WS-Policy and SOAP Message Security define a set of rules that determine the layout of security elements that appear in the WS-Security header in a SOAP message. The SAML assertion is inserted into the WS-Security header according to the layout option selected here. The available options correspond to the WS-Policy Layout assertions ofStrict, Lax, LaxTimestampFirst, and LaxTimestampLast.
Indent:
Select this method to ensure that the generated signature is properly indented.
Security Token Reference:
The generated SAML attribute assertion can be encapsulated in a <SecurityTokenReference> block. The following example demonstrates this:
<soap:Header>
<wsse:Security
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext"
soap:actor="axway">
<wsse:SecurityTokenReference>
<wsse:Embedded>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
ID="Id-0000010a3c4ff12c-0000000000000002"
IssueInstant="2006-03-27T15:26:12Z" Version="2.0">
<saml:Issuer Format="urn:oasis ... WindowsDomainQualifiedName">
TestCA
</saml:Issuer>
<saml:Subject>
<saml:NameID Format="urn:oasis ... WindowsDomainQualifiedName">
TestUser
</saml:NameID>
</saml:Subject>
<saml:Conditions NotBefore="2005-03-27T15:20:40Z"
NotOnOrAfter="2028-03-27T17:20:40Z"/>
<saml:AttributeStatement>
<saml:Attribute Name="role" NameFormat="http://www.example.com">
<saml:AttributeValue>admin</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="email" NameFormat="http://www.example.com">
<saml:AttributeValue>[email protected]</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="attrib1" NameFormat="">
<saml:AttributeValue xsi:nil="true"/>
<saml:AttributeValue>value1</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</wsse:Embedded>
</wsse:SecurityTokenReference>
</wsse:Security>
</soap:Header>
Axway API Gateway 7.5.2
Policy Developer Guide 450
11 Attribute filters
To add the SAML assertion to a <SecurityTokenReference> block like in this example, select the Embed SAML assertion within Security Token Reference option. Otherwise, select No Security Token Reference.
Retrieve attributes from JSON message
Overview
JSON Path is an XPath like query language for JSON (JavaScript Object Notation) that enables you to select nodes in a JSON document. The Retrieve Attributes with JSON Path filter enables you to retrieve specified message attributes from a JSON message using JSON Path expressions.
For more details on JSON Path, go to http://code.google.com/p/jsonpath/.
Configuration
Configure the following fields on the Retrieve Attributes with JSON Path filter window:
Name:
Enter an appropriate name for this filter to display in a policy.
Extract attributes using the following JSON Path expressions:
Specify the list of attributes for the API Gateway to retrieve using appropriate JSON Path expressions. All attribute values are stored in the attribute.lookup.list message attribute.
To add an attribute to the list, click the Add button, and enter the following values in the dialog:
l Attribute name:
Enter the message attribute name that you wish to extract using JSON Path (for example, bicycle.price).
l JSON Path Expression:
Enter the JSON Path expression that you wish to use to extract the message attribute (for example, $.store.bicycle.price). The Policy Studio prompts if you enter an unsupported JSON Path expression. l Unmarshal as:
Enter the data type to unmarshal the message attribute value as (defaults to java.lang.String).
l Fail if JSON Path Fails:
Select whether the filter should fail if the specified JSON Path expression fails. This option is not selected by default.
Note
If no attributes are specified, the API Gateway retrieves all the attributes in the message and sets them to the attribute.lookup.list attribute.
Axway API Gateway 7.5.2
Policy Developer Guide 451
11 Attribute filters
JSON Path examples
The following are some examples of using the Retrieve Attributes with JSON Path filter to retrieve data from a JSON message.
Retrieving attributes
The following example retrieves three different data items from the JSON message and stores them in the specified message attributes as strings:
When the extracted attributes are added to the content.body message attribute, the following example shows the corresponding request and response message in Axway API Tester:
Axway API Gateway 7.5.2
Policy Developer Guide 452
11 Attribute filters
Retrieving multiple attributes in a list
The following example retrieves all the authors from the JSON message and stores them in the specified message attribute as a List:
The following example shows the corresponding request and response in Axway API Tester:
Axway API Gateway 7.5.2
Policy Developer Guide 453
11 Attribute filters
Exceptions
The Retrieve Attributes with JSON Path filter aborts with a CircuitAbortException if the content body of the payload is not in valid JSON format.
Retrieve attribute from directory server
Overview
The API Gateway can leverage an existing directory server by querying it for user profile data. The Retrieve From Directory Server filter can look up a user and retrieve that user's attributes represented as a list of search results. Each element of the list represents a list of multivalued attributes returned from the directory server. Database settings
Configure the following fields on the Database tab:
LDAP Directory:
The API Gateway queries the selected Lightweight Directory Access Protocol (LDAP) directory for user attributes. An LDAP connection is retrieved from a pool of connections at runtime. Click the browse button to select the LDAP directory to query. To use an existing LDAP directory, (for example, Sample Active Directory Connection), select it in the tree. To add an LDAP directory, right-click the LDAP Connections tree node, and select Add an LDAP
Connection. Alternatively, you can add LDAP connections under the Environment
Configuration > External Connections node in the Policy Studio tree. For more details on how to configure LDAP connections, see Configure LDAP directories on page 418. Retrieve Unique User Identity
The Retrieve Unique User Identity section enables you to select the user whose profile the API Gateway looks up in the directory server. The user ID can be taken from a message attribute or looked up from an LDAP directory. Configure the following fields:
From Selector Expression:
Select this option if the user ID is stored in a message attribute, and specify the selector expression used to obtain its value at runtime (for example, ${authentication.subject.id}). A user's credentials are stored in the authentication.subject.id message attribute after authenticating to the API Gateway, so this is the most likely attribute to enter in this field. Axway API Gateway 7.5.2
Policy Developer Guide 454
11 Attribute filters
Typically, this contains the Distinguished Name (DName) or user name of the authenticated user. The name extracted from the specified message attribute is used to query the directory server. For more details on selector expressions, see Select configuration values at runtime on page 854.
From LDAP Search:
In cases where you have not already obtained the user's identity and the authentication.subject.id attribute has not been prepopulated by a prior authentication filter, you must configure the API Gateway to retrieve the user's identity from an LDAP search. Click the Configure Directory Search button to configure the search criteria to use to retrieve the user's unique DName from the LDAP repository. The User Search dialog is used to search a given LDAP directory for a unique user according to the criteria configured in the following fields: l Base Criteria:
The value entered here tells the API Gateway where it should begin searching the LDAP directory. For example, it might be appropriate to search for a given user under the C=IE tree in the LDAP hierarchy. l Query Search Filter:
The value entered here is what the API Gateway uses to determine whether it has obtained a successful match. In this case, because you are searching for a specific user, you can use the user name of an authenticated user (the value of the authentication.subject.id message attribute) to lookup in the LDAP directory. You must also specify the object class that defines users for the particular type of LDAP directory that you are searching against. For example, object classes representing users amongst common LDAP directories are inetOrgPerson, givenName, and User. For example, to search for an authenticated user against Microsoft's Active Directory, you might specify the following as the Query Search Filter:
(objectclass=User)(cn=${authentication.subject.id})
This example uses a selector to obtain the ID of the authenticated subject at runtime. For more details on selectors, see Select configuration values at runtime on page 854. l Search Scope:
These settings specify the depth of the LDAP tree to search. This depends largely on the structure of your LDAP directory.
Retrieve Attributes
The Retrieve Attributes section instructs the API Gateway to search the LDAP tree to locate a specific user profile. When the appropriate profile is retrieved, the API Gateway extracts the specified user attributes. Configure the following fields:
Base Criteria:
You can specify where the API Gateway should begin searching the LDAP directory using a selector. The selector represents the value of a message attribute that is expanded at runtime. The two most likely message attributes to be used here are the authenticated user's ID and Distinguished Name. Select one of the predefined selectors from the list:
Axway API Gateway 7.5.2
Policy Developer Guide 455
11 Attribute filters
l ${authentication.subject.id}
l ${authentication.subject.dname}
Alternatively, you can enter a selector representing other message attributes using the same syntax. For more details on selectors, see Select configuration values at runtime on page 854.
Search Filter:
This is the name given by the particular LDAP directory to the User class. This depends on the type of LDAP directory configured. You can also use a selector to represent the value of a message attribute. For example, you can use the user.role attribute to store the user class. The syntax for using the selector representing this attribute is as follows:
(objectclass=${user.role})
Search Scope:
If the API Gateway retrieves a user profile node from the LDAP tree, the option selected here dictates the level that the API Gateway searches the node to. The available options are:
l Object level
l One level
l Sub-tree
Unique Result:
Select this option to force the API Gateway to retrieve a unique user profile from the LDAP directory. This is useful in cases where the LDAP search has returned several profiles.
Attribute Name:
The Attribute Name table lists the attributes the API Gateway retrieves from the user profile. If no attributes are listed, the API Gateway extracts all user attributes. In both cases, retrieved attributes are set to the attribute.lookup.list message attribute. Click Add to add the name of an attribute to extract from the returned user profile. Enter the attribute name to extract from the profile in the Attribute Name field of the Attribute Lookup dialog.
Note
It is important to be aware of the following:
l If the search returns results for more than one user, and the Unique Result option is enabled, an error is generated. If this option is not enabled, all attributes are merged.
l If an attribute is configured that does not exist in the repository, no error is generated.
l If no attributes are configured, all attributes present for the user are retrieved.
Advanced settings
Configure the following fields on the Advanced tab:
Enable legacy attribute naming for retrieved attributes:
Specifies whether to enable legacy naming of retrieved message attributes. This field is not selected by default. Prior to version 7.1, retrieved attributes were stored in message attributes in the following format:
Axway API Gateway 7.5.2
Policy Developer Guide 456
11 Attribute filters
user.<retrieved_attribute_name>
For example, ${user.email}, ${user.role}, and so on. If the retrieved attribute was multivalued, you would access the values using ${user.email.1} or ${user.email.2}, and so on. In version 7.1 and later, by default, you can query for multivalued retrieved attributes using an array syntax (for example, ${user.email[0]}, or ${user.email[1]}, and so on). Select this setting to use the legacy format for attribute naming instead. Example of output attribute format with legacy attribute naming
The following table shows the output attribute format when legacy attribute naming is selected:
Prefix for message
attribute name
(optional)
Output attribute format (when attribute name is memberOf)
user (default)
l attribute.lookup.list: Map of retrieved attributes
l user.memberOf: When retrieves only a single value for the given attribute
l user.memberOf.* (for example, user.memberOf.1, user.memberOf.2, and so on): When retrieves multiple values for the given attribute
l ${user.memberOf}: Example selector
None
l attribute.lookup.list: Map of retrieved attributes
l memberOf: When retrieves only a single value for the given attribute
l memberOf.* (for example, memberOf.1, memberOf.2, and so on): When retrieves multiple values for the given attribute
l ${user.memberOf}: Example selector
Example of output attribute format without legacy attribute naming
The following table shows the output attribute format when legacy attribute naming is not selected:
Prefix for message
attribute name
(mandatory)
Output attribute format (when attribute name is
user.memberOf)
user (default)
l user: List of search results, where each element of the list corresponds to search results (pairs of attribute names and values)
l Example selector: ${user[0].memberOf[0]}
Prefix for message attribute:
You can specify an optional prefix for message attribute names. The default prefix is user. For more details, see Enable legacy attribute naming for retrieved attributes.
Axway API Gateway 7.5.2
Policy Developer Guide 457
11 Attribute filters
Note
When legacy attribute naming is not enabled, if you call the Retrieve from Directory
Server filter multiple times in a row, the results are appended to the original user attributes, instead of replacing them. For example, in single request, two Retrieve from Directory Server filters consecutively query an LDAP server for attributes, and both use the default prefix name of user. However, the attribute results of the second LDAP call do not replace the first results, and the user attribute gets a second entry instead. This means that to retrieve the attributes returned by the second call, you must use ${user[1].anotherattribute[0]}.
Retrieve attribute from HTTP header
Overview
The Retrieve from HTTP Header attribute retrieval filter can be used to retrieve the value of an HTTP header and set it to a message attribute. For example, this filter can retrieve an X.509 certificate from a USER_CERT HTTP header, and set it to the authentication.cert message attribute. This certificate can then be used by the filter's successors. The following HTTP request shows an example of such a header:
POST /services/getEmployee HTTP/1.1
Host:localhost:8095
Content-Length:21
SOAPAction:HelloService
USER_CERT:MIIEZDCCA0 ...9aKD1fEQgJ
You can also retrieve a value from a named query string parameter and set this to the specified message attribute. The following example shows a request URL that contains a query string:
http://hostname.com/services/getEmployee?first=john&last=smith
In the above example, the query string is first=john&last=smith . As is clear from the example, query strings consist of attribute name-value pairs. Each name-value pair is separated by the & character.
Configuration
The following fields are available on the Retrieve from HTTP Header filter configuration window:
Name:
Enter an appropriate name for this filter to display in a policy.
HTTP Header Name:
Enter the name of the HTTP header contains the value that we want to set to the message attribute.
Axway API Gateway 7.5.2
Policy Developer Guide 458
11 Attribute filters
Base64 Decode:
Check this box if the extracted value should be Base64 decoded before it is set to the message attribute.
Use Query String Parameters:
Select this setting if the API Gateway should attempt to extract the HTTP Header Name from the query string parameters instead of from the HTTP headers.
Attribute ID:
Finally, select the attribute used to store the value extracted from the request.
Retrieve attribute from SAML attribute
assertion
Overview
A SAML (Security Assertion Markup Language) attribute assertion contains information about a user in the form of a series of attributes. The Retrieve from SAML Attribute Assertion filter can retrieve these attributes and store them in the attribute.lookup.list message attribute.
The following SAML attribute assertion contains three attributes, "role", "email", and "dept". The Retrieve from SAML Attribute Assertion filter stores all three attributes and their values in the attribute.lookup.list message attribute.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
<soap:Header>
<wsse:Security>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
ID="Id-0000010a3c4ff12c-0000000000000002"
IssueInstant="2006-03-27T15:26:12Z" Version="2.0">
<saml:Issuer Format="urn:oasis ... WindowsDomainQualifiedName">
TestCA
</saml:Issuer>
<saml:Subject>
<saml:NameIdentifier Format="urn:oasis ... WindowsDomainQualifiedName">
TestUser
</saml:NameIdentifier>
</saml:Subject>
<saml:Conditions NotBefore="2005-03-27T15:20:40Z"
NotOnOrAfter="2028-03-27T17:20:40Z"/>
<saml:AttributeStatement>
<saml:Attribute Name="role" NameFormat="http://www.axway.com">
<saml:AttributeValue>admin</saml:AttributeValue>
Axway API Gateway 7.5.2
Policy Developer Guide 459
11 Attribute filters
</saml:Attribute>
<saml:Attribute Name="email" NameFormat="http://www.axway.com">
<saml:AttributeValue>[email protected]</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="dept" NameFormat="">
<saml:AttributeValue>engineering</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</wsse:Security>
</soap:Header>
<soap:Body>
<product>
<name>API Gateway</name>
<company>Axway</company>
<description>Web Services Security</description>
</product>
</soap:Body>
</soap:Envelope>
Details settings
The following fields are available on the Details tab:
SOAP Actor/Role:
If you expect the SAML assertion to be embedded within a WS-Security block, you can identify this block by specifying the SOAP Actor or Role of the WS-Security header that contains the assertion.
XPath Expression:
Alternatively, if the assertion is not contained within a WS-Security block, you can enter an XPath expression to locate the attribute assertion. XPath expressions can be added by selecting the Add button. Expressions can be edited and deleted by selecting an XPath expression and clicking the Add and Delete buttons respectively.
SAML Namespace:
Select the SAML namespace that must be used on the SAML assertion for this filter to succeed. If you do not wish to check the namespace, select the Do not check version option from the list.
SAML Version:
Enter the SAML version that the assertion must adhere to by entering the major version in the first field, followed by the minor version in the second field. For example, for SAML 2.0, enter 2 in the first field and 0 in the second field.
Drift Time:
When the API Gateway receives a SAML attribute assertion, it first checks to make sure that it has not expired. The lifetime of the assertion is specified using the NotBefore and NotOnOrAfter attributes of the <Conditions> element in the assertion itself. The API Gateway makes sure that the time at which it validates the assertion is between the NotBefore and NotOnOrAfter times.
Axway API Gateway 7.5.2
Policy Developer Guide 460
11 Attribute filters
The Drift Time is used to account for differences in the clock time of the machine that generated the assertion and the machine hosting the API Gateway. The time specified here is subtracted from the time at which the API Gateway attempts to validate the assertion. Trusted issuer settings
You can use the table on this tab to select the issuers that you consider trusted. In other words, this filter only accepts assertions that have been issued by the SAML authorities selected here. Click the Add button to display the Trusted Issuers window. Select the Distinguished Name of a SAML authority whose certificate has been added to the certificate store and click the OK button. Repeat this step to add more SAML authorities to the list of trusted issuers.
Subject settings
The API Gateway can perform some very basic authentication checks on the subject or sender of the assertion using the options available on the Subject tab. The API Gateway can compare the subject of the assertion (for example, the <NameIdentifier>) to one of the following values:
l The subject of the authentication filter:
Select this option if the user specified in the <NameIdentifier> element must match the user that authenticated to the API Gateway. The subject of the authentication event is stored in the authentication.subject.id message attribute.
l The following value:
This option can be used if the <NameIdentifier> must match a user-specified value. Select this radio button and enter the value in the field provided.
l Neither of the above:
If the Neither of the above radio button is selected, the API Gateway does not attempt to match the <NameIdentifier> to any value.
Lookup attributes settings
The Lookup Attributes tab is used to determine what attributes the API Gateway should extract from the SAML attribute assertion. Extracted attributes and their values are set to the attribute.lookup.list message attribute.
The table lists the attributes that the API Gateway extracts from the assertion and set to the attribute.lookup.list. Alternatively, check the Extract all of the attributes from the SAML assertion check box to configure the API Gateway to extract all attributes from the assertion. All attributes are set to the attribute.lookup.list message attribute.
Axway API Gateway 7.5.2
Policy Developer Guide 461
11 Attribute filters
To configure a specific attribute to look up in the message, click the Add button to display the Attribute Lookup dialog. Enter the value of the "Name" attribute of the <Attribute> element in the Attribute name field. Enter the value of the "NameFormat" attribute of the <Attribute> element in the Namespace field.
Retrieve attribute from SAML PDP
Overview
The API Gateway can request information about an authenticated end user in the form of user attributes from a SAML PDP (Policy Decision Point) using the SAML Protocol (SAMLP). In such cases, the API Gateway presents evidence to the PDP in the form of some user credentials, such as the Distinguished Name of a client's X.509 certificate. The PDP looks up its configured user store and retrieves attributes associated with that user. The attributes are inserted into a SAML attribute assertion and returned to the API Gateway in a SAMLP response. The assertion or SAMLP response is usually signed by the PDP.
When the API Gateway receives the SAMLP response, it performs a number of checks on the response, such as validating the PDP signature and certificate, and examining the assertion. It can also insert the SAML attribute assertion into the original message for consumption by a downstream web service.
Request settings
The Request tab describes how the API Gateway should package the SAMLP request before sending it to the SAML PDP. You can configure the following fields on the Request tab:
SAML PDP URL Set:
You can configure a group of SAML PDPs to which the API Gateway connects in a round-robin fashion if one or more of the PDPs are unavailable. This is known as a SAML PDP URL set. Click the button on the right, and select a previously configured SAML PDP URL set in the tree. To add a URL set, right-click the SAML PDP URL Sets tree node, and select Add a URL Set. Alternatively, you can configure a SAML PDP URL set under the Environment Configuration > External
Connections node in the Policy Studio tree.
SOAP Action:
Enter the SOAP action required to send SAMLP requests to the PDP. Click the Use Default button to use the following default SOAP action as specified by SAMLP:
http://www.oasis-open.org/committees/security
SAML Version:
Select the SAML version to use in the SAMLP request.
Axway API Gateway 7.5.2
Policy Developer Guide 462
11 Attribute filters
Signing Key:
If the SAMLP request is to be signed, click the Signing Key button, and select the appropriate signing key from the certificate store.
SAML subject settings
You can describe the subject of the SAML assertion on the SAML Subject tab. Complete the following fields:
Subject Selector Expression:
Enter a selector expression for the message attribute that contains the user name of an authenticated user. The default value is ${authentication.subject.id}.
Subject Format:
Select the format of the subject selected in the Subject Selector Expression field above. Note
There is no need to select a format here if the Subject Attribute field is set to authentication.subject.id.
Subject confirmation settings
The settings on the Subject Confirmation tab determine how the <SubjectConfirmation>
block of the SAML assertion is generated. When the assertion is consumed by a downstream web service, the information contained in the <SubjectConfirmation> block can be used to authenticate either the end user that authenticated to the API Gateway, or the issuer of the assertion, depending on what is configured.
The following is a typical <SubjectConfirmation> block:
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>
urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
</saml:ConfirmationMethod>
<dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
<dsig:X509Data>
<dsig:X509SubjectName>CN=axway</dsig:X509SubjectName>
<dsig:X509Certificate>
MIICmzCCAY ...... mB9CJEw4Q=
</dsig:X509Certificate>
</dsig:X509Data>
</dsig:KeyInfo>
</saml:SubjectConfirmation>
You must configure the following fields on the Subject Confirmation tab:
Method:
The selected value determines the value of the <ConfirmationMethod> element. The following table shows the available methods, their meanings, and their respective values in the <ConfirmationMethod> element:
Axway API Gateway 7.5.2
Policy Developer Guide 463
11 Attribute filters
Metho
d
Meaning
Value
Holder Of Key
A <SubjectConfirmation> is urn:oasis:names:tc:SAML:1.0:c
inserted into the SAMLP request. The m:
<SubjectConfirmation> holder-of-key
contains a <dsig:KeyInfo> section with the certificate of the user selected to sign the SAMLP request. The user selected to sign the SAMLP request must be the authenticated subject (
authentication.subject.i
d).
Select the Include Certificate option if the signer's certificate is to be included in the SubjectConfirmation block. Alternatively, select the Include
Key Name option if only the key name is to be included. Bearer
A <SubjectConfirmation> is urn:oasis:names:tc:SAML:1.0:c
inserted into the SAMLP request.
m:
bearer
SAML Artifact
A <SubjectConfirmation> is urn:oasis:names:tc:SAML:1.0:c
inserted into the SAMLP request.
m:
artifact
Sender Vouche
s
A <SubjectConfirmation> is urn:oasis:names:tc:SAML:1.0:c
inserted into the SAMLP request. The m:
SAMLP request must be signed by a bearer
user. If the Method field is left blank, no <ConfirmationMethod> block is inserted into the assertion.
Include Certificate:
Select this option to include the SAML subject's certificate in the <KeyInfo> section of the <SubjectConfirmation> block.
Include Key Name:
Alternatively, if you do not want to include the certificate, you can select this option to only include the key name in the <KeyInfo> section.
Axway API Gateway 7.5.2
Policy Developer Guide 464
11 Attribute filters
Attributes
You can list a number of user attributes to include in the SAML attribute assertion that is generated by the API Gateway. If no attributes are explicitly listed in this section, the API Gateway inserts all attributes associated with the user (all user attributes in the attribute.lookup.list message attribute) in the assertion.
To add a specific attribute to the SAML attribute assertion, click the Add button. A user attribute can be configured using the Attribute Lookup dialog. Enter the name of the attribute that is added to the assertion in the Attribute name field. Enter the namespace that is associated with this attribute in the Namespace field. You can edit and remove previously configured attributes using the Edit and Remove buttons.
Response settings
The Response tab configures the SAMLP response returned from the SAML PDP. The following fields are available:
SOAP Actor/Role:
If the SAMLP response from the PDP contains a SAML attribute assertion, the API Gateway can extract it from the response and insert it into the downstream message. The SAML assertion is inserted into the WS-Security block identified by the specified SOAP actor/role. Drift Time:
The SAMLP request to the PDP is time stamped by the API Gateway. To account for differences in the times on the machines running the API Gateway and the SAML PDP the specified time is subtracted from the time at which the API Gateway generates the SAMLP request.
Retrieve attribute from Tivoli
You can use the Retrieve from Tivoli filter when you need to retrieve user attributes independently from authorizing the user against Tivoli Access Manager for e-business. This filter is found in the Attributes category.
For details on prerequisites for integration with IBM Tivoli, see the API Gateway Authentication and Authorization Integration Guide.
Configuration
Complete the following fields to configure the Retrieve from Tivoli filter:
Name:
Enter an appropriate name for the filter to display in a policy.
Axway API Gateway 7.5.2
Policy Developer Guide 465
11 Attribute filters
User ID:
Enter the ID of a user to retrieve attributes for. You can enter a static user name, Distinguished Name (DName), or selector representing a message attribute. The selector is expanded to the value of the message attribute at runtime.
For example, you can enter ${authentication.subject.id}. This means that the ID of the authenticated user, which is normally a DName, is used to retrieve attributes for. For this to work correctly, you must configure an authentication filter to run before this filter in the policy. For more details on selectors, see Select configuration values at runtime on page 854.
Attributes:
You can specify a list of user attributes to retrieve from the Tivoli server. To add individual attributes to be retrieved, click Add and enter the attributes in the dialog. If you want all attributes to be retrieved, leave the table blank.
Tivoli Configuration Files:
A Tivoli configuration file that contains all the required connection details is associated with a particular API Gateway instance. Click Settings to display the Tivoli Configuration dialog. On the Tivoli Configuration dialog, select the API Gateway instance which connection details you want to edit. For more details on configuring this wizard, see Configure Tivoli connections on page 429.
Retrieve attribute from message
Overview
The Retrieve from Message filter uses XPath expressions to extract the value of an XML element or attribute from the message and set it to an internal message attribute. The XPath expression can also return a NodeList, and the NodeList can be set to the specified message attribute.
Configuration
The following fields are available on the Retrieve from Message filter configuration window:
Name:
Enter an appropriate name for this filter to display in a policy.
Use the following XPath:
Configure an XPath expression to retrieve the desired content. Click the Add button to add an XPath expression. You can add and remove existing expressions by clicking the Edit and Remove buttons respectively.
Store the extracted content:
Select an option to specify how the extracted content is stored. The options are:
l of the node as text (java.lang.String)
This option saves the content of the node retrieved from the XPath expression to the specified Axway API Gateway 7.5.2
Policy Developer Guide 466
11 Attribute filters
message attribute as a String.
l for all nodes found as text (java.lang.String)
This option saves all nodes retrieved from the XPath expression to the specified message attribute as a String (for example, <node1>test</node1>). This option is useful for extracting <Signature>, <Security>, and <UsernameToken> blocks, as well as proprietary blocks of XML from messages.
l for all nodes found as a list (java.util.List)
This option saves the nodes retrieved from the XPath expression to the specified message attribute as a Java List, where each item is of type Node. For example, if the XPath returns <node1>test</node1>, there is one node in the List ( <node1>). The child text node ( test) is accessible from that node, but is not saved as an entry in the List at the top-level.
Extracted content will be stored in attribute named:
The API Gateway sets the value of the message attribute selected here to the value extracted from the message. You can also enter a user-defined message attribute.
Optionally the message payload can be replaced by the extracted content:
Select this option to take the value being set into the attribute and add it to the content body of the response. This option is not selected by default.
Use the following content type for new payload:
This field is only available if the preceding option is selected. This allows you to specify the content type for the response, based on what is added to the content body.
Retrieve attribute from database
Overview
The API Gateway can retrieve user attributes from a specified database, or write user attributes to a specified database. It can do this by running an SQL query on the database, or by invoking a stored procedure call. The query results are represented as a list of properties. Each element in the list represents a query result row returned from the database for the specified SQL query or stored procedure call. These properties represent pairs of attribute names and values for each column in the row.
Database settings
Configure the following fields on the Database tab:
Database Location:
The API Gateway searches the selected database for the user's attributes. Click the browse button to select the database to search. To use an existing database connection (for example, Default
Database Connection), select it in the tree. To add a database connection, right-click the Axway API Gateway 7.5.2
Policy Developer Guide 467
11 Attribute filters
Database Connections tree node, and select Add DB connection. Alternatively, you can add database connections under the Environment Configuration > External Connections node in the Policy Studio tree view. For more information on configuring database connections, see Configure database connections on page 399.
Database Statements:
The Database Statements table lists the currently configured SQL queries or stored procedure calls. These queries and calls retrieve certain user attributes from the database selected in the Database Location field. You can edit and delete existing queries by selecting them from the drop-down list and clicking the Edit and Delete buttons. For more information on how to configure a Database Query, see Configure database queries on page 402.
Advanced settings
On the Advanced tab, configure the following fields in the User Attribute Extraction section:
Place query results into user attribute list:
Select whether to place database query results in message attributes. When selected, the message attribute names are generated based on the message attribute prefix and the attribute name. For example, if the specified prefix is user and the attributes are PHONE and EMAIL, the user.PHONE and user.EMAIL attributes are generated. This setting is selected by default. Associate attributes with user ID returned by selector:
When the Place query results into message attribute list setting is selected, you can specify a user ID to associate with the user attributes. For example, if the user name is stored as admin in the database, you must select the message attribute containing the value admin. The API Gateway then looks up the database using this name. By default, the user ID is stored in the ${authentication.subject.id} message attribute. Configure the following fields on the Attribute Naming section:
Enable legacy attribute naming for retrieved attributes:
Specifies whether to enable legacy naming of retrieved message attributes. This field is not selected by default. Prior to version 7.1, retrieved attributes were stored in message attributes in the following format:
user.<retrieved_attribute_name>
For example, ${user.email}, ${user.role}, and so on. If the retrieved attribute was multivalued, you would access the values using ${user.email.1} or ${user.email.2}, and so on. In version 7.1 and later, by default, you can query for multivalued retrieved attributes using an array syntax (for example, ${user.email[0]}, or ${user.email[1]}, and so on). Select this setting to use the legacy format for attribute naming instead.
Example of output attribute format with legacy attribute naming
The following table shows the output attribute format when legacy attribute naming is selected:
Axway API Gateway 7.5.2
Policy Developer Guide 468
11 Attribute filters
Place query results
into user attribute list
Prefix for message
attribute name
(optional)
Output attribute format (when
attribute name is PHONE)
Selected (default)
user (default)
l attribute.lookup.list: Map of retrieved attributes
l user.PHONE: Attribute value
l ${user.PHONE}: Example selector
Selected (default)
None
l attribute.lookup.list: Map of retrieved attributes
l PHONE: Attribute value
l ${PHONE}: Example selector
Not selected
user (default)
l user.PHONE: Attribute value
l ${user.PHONE}: Example selector
Not selected
None
l PHONE: Attribute value
l ${PHONE}: Example selector
Example of output attribute format without legacy attribute naming
The following table shows the output attribute format when legacy attribute naming is not selected:
Place query
results into user
attribute list
Prefix for message
attribute name
(mandatory)
Output attribute format (when attribute
name is PHONE)
Selected (default)
user (default)
l user: List of properties, where each corresponds to a retrieved row (attribute name and value pair)
l ${user[0].PHONE}: Example selector
Not selected
user (default)
l user.PHONE: List of properties, where each corresponds to a retrieved row (attribute name and value pair)
l ${user.PHONE[0]}: Example selector
Prefix for message attribute:
Specifies an optional prefix for message attribute names used to store query results. The default prefix is user. For more details, see Place query results into user attribute list and Enable
legacy attribute naming for retrieved attributes.
Axway API Gateway 7.5.2
Policy Developer Guide 469
11 Attribute filters
Attribute name for stored procedure out parameters:
You can also specify an attribute name for stored procedure out parameters. The default prefix is out.param.value.
Case for attribute names:
You can specify whether attribute names are in lower case or upper case. The default is lower case.
Configure the following fields on the Result Set Options section:
Fail on empty result set:
Specify whether this filter fails if the result set is empty. This setting is not selected by default.
Attribute name for result set size:
Specify the attribute name used to store the size of the result set. Defaults to db.result.count.
Retrieve attribute from user store
Overview
The API Gateway user store contains user profiles, including attributes relating to each user. After a user has successfully authenticated to the API Gateway, the Retrieve From User Store filter can retrieve attributes belonging to that user from the user store.
Database settings
Configure the following fields on the Database tab:
User ID:
Select or enter the name of the message attribute that contains the name of the user to look up in the user store. For example, if the user name is stored as admin, select the message attribute containing the value admin. The API Gateway then looks up the user in the user store using this name.
Attributes:
Enter the list of attributes that the API Gateway should retrieve if it successfully looks up the user specified by the User ID field. To add attributes, click the Add button. Similarly, to edit or remove existing attributes, click the Edit or Remove buttons.
Advanced settings
Configure the following fields on the Advanced tab:
Axway API Gateway 7.5.2
Policy Developer Guide 470
11 Attribute filters
Enable legacy attribute naming for retrieved attributes:
Specifies whether to enable legacy naming of retrieved message attributes. This field is not selected by default. Prior to version 7.1, retrieved attributes were stored in message attributes in the following format:
user.<retrieved_attribute_name>
For example, ${user.email}, ${user.role}, and so on. If the retrieved attribute was multivalued, you would access the values using ${user.email.1} or ${user.email.2}, and so on. In version 7.1 and later, by default, you can query for multivalued retrieved attributes using an array syntax (for example, ${user.email[0]}, or ${user.email[1]}, and so on). Select this setting to use the legacy format for attribute naming instead. Prefix for message attribute:
You can specify an optional prefix for message attribute names. The default prefix is user.
Fail on empty result set:
Specify whether this filter fails if the result set is empty. This setting is not selected by default.
Axway API Gateway 7.5.2
Policy Developer Guide 471
Authentication filters
12
The following filters enable you to perform authentication with API Gateway:
Attribute authentication
472
API key authentication
474
Check session
478
Create session
478
End session
480
CA SOA Security Manager authentication
481
HTML form-based authentication
484
HTTP basic authentication
487
HTTP digest authentication
489
HTTP header authentication
491
IP address authentication
492
Insert SAML authentication assertion
495
Insert timestamp
502
Insert WS-Security UsernameToken
503
Kerberos client authentication
505
Kerberos service authentication
507
SAML authentication
510
SAML PDP authentication
512
SSL authentication
516
STS client authentication
516
WS-Security UsernameToken authentication
526
Attribute authentication
Overview
In cases when user credentials are passed to the API Gateway in a non-standard way, the credentials can be copied into API Gateway message attributes, and authenticated against a specified authentication repository (for example, API Gateway user store, LDAP directory, or database) using an Attribute Authentication filter. For example, assume user credentials are passed to API Gateway in the following XML message:
Axway API Gateway 7.5.2
Policy Developer Guide 472
12 Authentication filters
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ns:User xmlns:ns="http://www.user.com">
<ns:Username>1</ns:Username>
<ns:Password>2</ns:Password>
</ns:User>
</s:Body>
</s:Envelope>
In this example, the standard methods of passing credentials (for example, HTTP basic or digest authentication, SAML assertions, and WS-Security Username tokens) are bypassed, and the client sends the user name and password as parameters in a simple SOAP message. When the API Gateway receives this message, it can extract the value of the <Username> and <Password> elements using an XPath expression configured in the Retrieve from Message filter. This filter uses an XPath expression to retrieve the value of an element or attribute, and can then store this value in the specified message attribute. You can configure an instance of this filter to retrieve the value of the <Username> attribute, and store it in the authentication.subject.id message attribute. Similarly, you can configure another filter to retrieve the value of the <Password>, and store it in the authentication.subject.password message attribute.
The Attribute Authentication filter can then use the user name and password values stored in these message attributes to authenticate the user against the specified authentication repository. Configuration
Complete the following fields to configure this filter:
Name:
Enter an appropriate name for this filter to display in a policy.
Username:
Specify the API Gateway message attribute that contains the user name of the user to be authenticated. The default attribute is the authentication.subject.id attribute, which is typically used to store a user name. Password:
Enter the API Gateway message attribute that contains the password of the user to authenticate. The default message attribute is authentication.subject.password, which typically stores a password.
Credential Format:
Select the format of the credential stored in the API Gateway message attribute specified in the Username field above. By default, User Name is selected. Axway API Gateway 7.5.2
Policy Developer Guide 473
12 Authentication filters
Repository Name:
Select an existing repository to authenticate the user against from the list. Alternatively, you can configure a new authentication repository by clicking the Add button. For more details on configuring the various types of repository supported by the API Gateway, see Configure authentication repositories on page 377.
API key authentication
Overview
API keys are supplied by client users and applications calling REST APIs to track and control how the APIs are used (for example, to meter access and prevent abuse or malicious attack). The Authenticate API Key filter enables you to securely authenticate an API key with the API Gateway. API keys include a key ID that identifies the client responsible for the API service request. This key ID is not a secret, and must be included in each request. API keys can also include a confidential secret key used for authentication, which should only be known to the client and to the API service. You can use the Authenticate API Key filter to specify where to find the API key ID and secret key in the request message, and to specify timestamp and expiry options.
An example use case for this filter would be a client accessing a REST API service to invoke specific methods (for example, startVM() or stopVM()). To invoke these methods, you are required to provide your API key ID and secret key to the API Gateway. You can keep the secret key private by sending the request over HTTPS. Alternatively, you can use the secret key to generate an HMAC digital signature. This means that the secret key is not sent in the request, but is inferred instead, because the message must have been signed using the required secret key. When the API service receives the request, it uses the API key ID to look up the corresponding secret key, and uses it to validate the signature and confirm the request sender.
The API Gateway supports the following API key types:
l Simple API keys including a key ID only. The API key ID is included in all requests to authenticate the client.
l Amazon Web Services style API keys including a key ID and a secret key, which are used together to securely authenticate the client. The API key ID is included in all requests to identify the client. The secret key is known only to the client and the API Gateway.
For more details on authenticating Amazon Web Services API keys, go to:
http://s3.amazonaws.com/doc/s3-developer-guide/RESTAuthentication.html
General settings
Configure the following general settings:
Axway API Gateway 7.5.2
Policy Developer Guide 474
12 Authentication filters
Name:
Enter a suitable name for this filter in your policy.
KPS Alias:
Enter the alias name of the Key Property Store (KPS) used to store the API keys. For more details, see Key Property Store on page 273. Defaults to the example ClientRegistry supplied with the API Gateway. For details on storing API keys in the Axway Client Application Registry, see the API Gateway OAuth User Guide. Field Containing Secret:
Enter the name of the field in the KPS that contains the secret. Defaults to secretKey.
API key settings
Configure the following fields on the API Key tab:
Where to find API key:
To specify where to find the API key in the request message, select one of the following options:
l API key is located in:
Select one of the following from the list: o Query String
o Header
o Parameter
The default option is Query String. Enter the name in the text box. Defaults to KeyId. l API key is in Authorization header with format:
Select one of the following Authorization headers from the list: o Amazon AWS s3 Authorization Header - "AWS apiKey + ":" +
base64(signature)"
o HTTP Basic Authentication Header - "Basic base64
(apiKey:secret)"
Defaults to the Amazon AWS s3 Authorization Header. l API key can be found using the following selector:
Enter the selector value that specifies the location of the API key. For details on selectors, see Select configuration values at runtime on page 854. Defaults to ${http.client.getCgiArgument("KeyId")}. Where to find Secret key:
To specify where to find the secret key in the request message, select the Extract Secret setting, and select one of the following options:
Axway API Gateway 7.5.2
Policy Developer Guide 475
12 Authentication filters
l Secret key is in:
Select one of the following from the list:
o Query String
o Header
o Parameter
The default option is Query String. Enter the name in the text box. Defaults to SecretKey. l Secret key is in Authorization header with format:
Select the Authorization header from the list. Defaults to HTTP Basic Authentication
Header - "Basic base64(apiKey:secret)". l Secret key can be inferred from signature:
The client can use the secret key to generate a digital signature that is included in the request. When the API Gateway receives the request, it uses the API key ID to identify the client and look up the corresponding secret key in the Axway Client Application Registry. The secret key is then used to validate the signature and authenticate the client. To specify the signature format, select one of the following from the list: o Amazon AWS s3 Authorization Header Authentication - "AWS
apiKey + ":" + base64(signature)"
o Amazon AWS s3 REST Authentication - "?Signature=<base64
(signature)>
&Expires=<seconds since epoch>&AWSAccessKeyId=<aws-id>"
Defaults to Amazon AWS s3 Authorization Header Authentication. l Secret key can be found using the following selector:
Enter the selector value that specifies the location of the secret key. For details on selectors, see Select configuration values at runtime on page 854. Defaults to ${http.client.getCgiArgument("SecretKey")}. Authenticate API key and secret:
Select whether to authenticate both the API key ID and the secret key. This means that the client must supply the API key ID and the secret key in the request message. This setting is selected by default.
Advanced settings
Configure the following fields on the Advanced tab:
Validate Timestamp:
Select whether to validate the API key timestamp using the settings specified below. This setting is unselected by default.
Axway API Gateway 7.5.2
Policy Developer Guide 476
12 Authentication filters
Timestamp is located in:
To specify where the timestamp is located in the request message, select one of the following from the list: l Header
l Parameter
l Query String
The default option is Header. Enter the name in the text box. Defaults to Date. Timestamp format is :
To specify the timestamp format, select one of the following from the list: l Simple Date Format
l Milliseconds since epoch
l Seconds since epoch
The default option is Simple Date Format. Enter the format in the text box. Defaults to EEE,
dd MMM yyyy HH:mm:ss zzz. Timestamp Drift +/-:
You can specify a drift time in milliseconds to allow differences in the clock times between the machine on which the API key was generated and the machine on which the API Gateway is running. Defaults to +-60000 milliseconds (one minute). Validate Expires:
Select whether to validate the API key expiry details using the settings specified below. This setting is unselected by default.
Expires is located in:
To specify the location of the expiry details in the request message, select one of the following from the list: l Query String
l Header
l Parameter
The default option is Query String. Enter the name in the text box. Defaults to Expires. Expires format is:
To specify the format of the expiry details, select one of the following from the list: l Milliseconds since epoch
l Seconds since epoch
l Simple Date Format
The default option is Milliseconds since epoch. Enter the format in the text box. Axway API Gateway 7.5.2
Policy Developer Guide 477
12 Authentication filters
Timestamp Drift +/-:
You can specify a drift time in milliseconds to allow differences in the clock times between the machine on which the API key was generated and the machine on which the API Gateway is running. Defaults to 60000 milliseconds (one minute). Check session
Overview
The Check Session filter checks for the presence of a valid cookie-based HTTP session. This filter tries to locate a valid session based on the value of a specified cookie name. If the session is found, the filter retrieves the user and sets it in the authentication.subject.id attribute.
The Check Session filter should be used with the Create Session and End Session filters to manage HTTP sessions. For more details, see:
l Create session on page 478
l End session on page 480
Configuration
Complete the following fields to configure this filter:
Name:
Enter an appropriate name for this filter to display in a policy.
Session cookie:
Enter the name of the HTTP cookie used for the session. This filter tries to locate a valid session based on the value of the specified cookie name. The cookie name is output in the generated http.session.cookie.name message attribute. Defaults to VIDUSR. Create session
Overview
The Create Session filter enables the API Gateway to create an HTTP session and configure various session attributes (for example, expiry, domain, and security). This filter requires an authentication.subject.id attribute for the user, and stores it in the HTTP session. This Axway API Gateway 7.5.2
Policy Developer Guide 478
12 Authentication filters
session ID is used to create a cookie with a specified name, which is stored in the generated http.session.cookie.name attribute. The cookie is then sent to the user specified by the authentication.subject.id attribute.
The Create Session filter should be used with the Check Session and End Session filters to manage HTTP sessions. For more details, see:
l Check session on page 478
l End session on page 480
Tip
The Create Session filter offers a more flexible approach to managing HTTP sessions than using the HTTP Form-Based Authentication filter. For example, the form-based approach does not include the ability to check or end sessions, and sessions are autorenewed on each invocation of the filter. For more details, see HTML form-based authentication on page 484.
Configuration
Complete the following fields to configure this filter:
Name:
Enter an appropriate name for this filter to display in a policy.
Expiration time of session in milliseconds:
Enter the HTTP session expiry timeout in milliseconds. When the session reaches the specified lifetime, it is automatically invalidated, and can no longer pass the Check Session filter.
Session cookie:
Enter the name of the HTTP cookie used for the session. This filter uses the HTTP session ID to create the cookie named by this field. The specified cookie name is output in the generated http.session.cookie.name message attribute. Defaults to VIDUSR. Session cookie domain:
Enter the domain value for the Set-Cookie header (for example, example.com).This informs the browser that cookies should be sent back to the server for the specified domain only. Session cookie path:
Enter the path value for the Set-Cookie header (for example, /sales). This informs the browser that cookies should be sent back to the server for the specified path only. Defaults to /.
Session sent over SSL only:
Select whether the session uses SSL only. When selected, this adds a Secure flag to the cookie.
HTTP-only cookie:
Select whether the session uses HTTP only. When selected, this adds an HTTPOnly flag to the cookie.
Axway API Gateway 7.5.2
Policy Developer Guide 479
12 Authentication filters
End session
Overview
The End Session filter terminates a cookie-based HTTP session. This filter tries to locate the session based on the value of a specified cookie name, and then invalidates it.
The End Session filter should be used with the Create Session and Check Session filters to manage HTTP sessions. For more details, see:
l Create session on page 478
l Check session on page 478
Configuration
Complete the following fields to configure this filter:
Name:
Enter an appropriate name for this filter to display in a policy.
Remove session cookie:
Select whether to try and remove the session cookie. When selected, the API Gateway sends a new cookie with the expiry time set in the past. You must also set the same domain and path values that were used to create the session using the Create Session filter. Session cookie:
Enter the name of the HTTP cookie used for the session. This filter tries to locate the session specified by this cookie name. This is output in the generated http.session.cookie.name message attribute. Defaults to VIDUSR. Session cookie domain:
When Remove session cookie is selected, enter the same domain that was used to create the session in the Create Session filter (for example, example.com). This removes the cookie for the specified domain only. Session cookie path:
When Remove session cookie is selected, enter the same path that was used to create the session in the Create Session filter (for example, /sales). This removes the cookie for the specified path only. Defaults to /.
Axway API Gateway 7.5.2
Policy Developer Guide 480
12 Authentication filters
CA SOA Security Manager authentication
Overview
CA SOA Security Manager can authenticate end users and authorize them to access protected web resources. When the API Gateway receives a message containing user credentials, it can forward the message to CA SOA Security Manager where the passed credentials are extracted from the message to authenticate the end user. When the message has been passed to CA SOA Security Manager, it can authenticate the user by the following methods:
l XML Document Credential Collector:
Gathers credentials from the message and maps them to fields within a user directory.
l XML Digital Signature:
Validates the X.509 certificate contained within an XML-Signature on the message.
l WS-Security:
Extracts user credentials from WS-Security tokens contained in the message.
l SAML Session Ticket:
Consumes a SAML session ticket from an HTTP header, SOAP envelope, or session cookie to authenticate the end user.
By delegating the authentication decision to CA SOA Security Manager, the API Gateway acts as a Policy Enforcement Point (PEP). It enforces the decisions made by the CA SOA Security Manager, which acts a Policy Decision Point (PDP). For more details, see the CA SOA Security Manager Policy Configuration Guide. Prerequisites
Integration with CA SOA Security Manager requires CA TransactionMinder SDK version 6.0 or later. You must add the required third-party binaries to your API Gateway and Policy Studio installations.
Add third-party binaries to API Gateway
To add third-party binaries to API Gateway, perform the following steps:
1. Add the binary files as follows:
l Add .jar files to the INSTALL_DIR/apigateway/ext/lib directory.
l Add .dll files to the INSTALL_DIR\apigateway\Win32\lib directory.
l Add .so files to the INSTALL_DIR/apigateway/<platform>/lib directory.
2. Restart API Gateway.
Add third-party binaries to Policy Studio
To add third-party binaries to Policy Studio, perform the following steps:
Axway API Gateway 7.5.2
Policy Developer Guide 481
12 Authentication filters
1. Select Windows > Preferences > Runtime Dependencies in the Policy Studio main menu.
2. Click Add to select a JAR file to add to the list of dependencies.
3. Click Apply when finished. A copy of the JAR file is added to the plugins directory in your Policy Studio installation.
4. Click OK.
5. Restart Policy Studio with the -clean option. For example:
> cd INSTALL_DIR/policystudio/
> policystudio -clean
Configuration
Name:
Enter a name for this filter to display in a policy.
Agent Name:
To act as a PEP for the CA SOA Security Manager, the API Gateway must have been set up as a SOA Agent with the Policy Server. For more details on how to do this, see the CA SOA Security Manager Agent Configuration Guide.
Click the button on the right to select a previously configured agent to connect to SOA Security Manager. This name must correspond with the name of an agent previously configured in the SOA Security Manager Policy Server. At runtime, the API Gateway connects as this agent to a running instance of SOA Security Manager.
To add an agent, right-click the SiteMinder/SOA Security Manager Connections tree node, and select Add a SOA Security Manager Connection. Alternatively, you can add SOA Security Manager connections under the Environment Configuration > External Connections node in the Policy Studio tree. For details on how to configure SOA Security Manager connections, see SOA Security Manager connection settings on page 426. Message details settings
While authenticating the user against CA SOA Security Manager, the user can also be authorized for a specified action on a particular resource. Configure the following fields in the Message Details section:
Resource:
Enter the name of the resource for which you want to ensure that the user has access to. By default, the http.request.uri message attribute is used, which contains the relative path on which the request was received by the API Gateway.
Axway API Gateway 7.5.2
Policy Developer Guide 482
12 Authentication filters
Action:
Specify the action that the user is attempting to perform on the specified resource. The API Gateway checks the user's entitlements in CA SOA Security Manager to ensure that the user is allowed to perform this action on the resource entered above. By default, the http.request.verb message attribute is used, which stores the HTTP verb used by the client when sending up the message.
Protocol:
Enter the protocol used by the client to access the requested resource. Users can have different access rights depending on their roles in the organization. For example, managers might be allowed to FTP to a given resource, but more junior employees might only be allowed to GET a resource using HTTP. Defaults to http.
Headers:
To carry out further authorization checks on the message, it is possible to forward the HTTP headers associated with the client message to the CA SOA Security Manager. By default, the http.headers message attribute is used to ensure that the original client headers are send to the CA SOA Security Manager.
XmlToolkit.properties file
The XmlToolkit.properties file contains default properties used by the SOA agent, such as the URL of the CA SOA Manager, an identifier for the SOA agent, and an indication to the SOA Manager if it should perform fine-grained resource identification or not. The XmlToolkit.properties file can be found in the /lib/modules/soasm directory of your API Gateway installation.
#Wed Jul 18 15:02:16 BST 2007
WSDMResourceIdentification=yes
WS_UT_CREATION_EXPIRATION_MINUTES=60
The following properties are available:
l WSDMResourceIdentification
This value cannot be configured from the Policy Studio, and so can only be set directly in the properties file. If this property is set to no (or if the properties file cannot be found) only a coarse-grained resource identification is performed on the requested URL. If this value is set to yes, a fine-grained resource identification including the requested URL, web service name, and SOAP operation ( <url>/<web service name>/<soap operation>).
l WS_UT_CREATION_EXPIRATION_MINUTES
Specifies the WS-Username Token age limit restriction in minutes. This setting helps prevent against replay attacks. The default token age limit is 60 minutes. See the following section for more information on modifying this setting.
Axway API Gateway 7.5.2
Policy Developer Guide 483
12 Authentication filters
Configure the user name and password digest token
age restriction
By default, the WS-Security authentication scheme imposes a 60 minute restriction on the age of user name and password digest tokens to protect against replay attacks.
You can configure a different value for the token age restriction for the API Gateway by setting the WS_UT_CREATION_EXPIRATION_MINUTES parameter in the XmlToolkit.properties file for that API Gateway. To configure the API Gateway to use a non-default age restriction for user name and password token authentication, complete the following steps:
1. Navigate to the<INSTALL_DIR>/system/lib/modules/soasm directory, where INSTALL_DIR points to the root of your API Gateway installation.
2. Open the XmlToolkit.properties file in a text editor.
3. Add the following line, where token_age_limit specifies the token age limit in minutes:
WS_UT_CREATION_EXPIRATION_MINUTES=token_age_limit
4. Save and close the XmlToolkit.properties file.
5. Restart API Gateway.
Note
It is important to note the following:
l The properties file is written to the /lib/modules/soasm directory when a SOA Security Manager Authentication or Authorization filter is loaded at startup, or on server refresh (for example, when a configuration update is deployed), but only if the file does not already exist in this location.
l If the properties file already exists in the /lib/modules/soasm directory, the WSDMResourceIdentification property is not overwritten. In other words, the user is allowed to manually set this property independently of the Policy Studio.
l If the WSDMResourceIdentification property does not exist, it is given a default value of yes and written to the file.
HTML form-based authentication
Overview
HTML form-based authentication enables users to supply their user name and password details in an HTML form, and submit them to login to a system. Using HTML form-based authentication, normal HTTP authentication features such as HTTP basic or HTTP digest are not used. Instead, the user name and password are typically sent as HTML <FORM> data in an HTTP POST over SSL. Axway API Gateway 7.5.2
Policy Developer Guide 484
12 Authentication filters
When the HTML Form based Authentication filter is configured, the API Gateway can authenticate the user details specified in the HTML form against a user profile stored in the API Gateway local repository, a database, or an LDAP directory. The HTML Form based
Authentication filter also enables you to specify how HTTP sessions are managed (for example, session expiry, and applicable API Gateway domain or relative path). Tip
For an alternative approach to HTTP session management, which also includes the ability to check or to end sessions, see Create session on page 478. General settings
These settings enable you to configure general details such as the names of the HTML form fields, format of user credentials, and repository to validate credentials against. Complete the following settings:
Name:
Enter an appropriate name for the filter to display in a policy.
Username:
Enter the name of the HTML form field in which the user enters their user name. Defaults to username.
Password:
Enter the name of the HTML form field in which the user enters their password. Defaults to password.
Format of Authentication Credentials:
You must specify the format of the user credentials presented by the client because the API Gateway has no way of telling one credential format from another. Select one of the following from the list:
l User Name
l X.509 Distinguished Name
The selected format is then used internally by the API Gateway when performing authorization lookups against third-party Identity Management servers.
Repository Name:
This specifies the name of the authentication repository where all user profiles are stored. This can be in the API Gateway's local repository, a database, or an LDAP directory. Select a preconfigured repository from the list (for example, Local User Store). You can add a new repository by right-clicking the appropriate node under Environment
Configuration > External Connections > Authentication Repository Profiles (for example, Database Repositories), and selecting Add a new Repository. For more details, see Configure authentication repositories on page 377.
Axway API Gateway 7.5.2
Policy Developer Guide 485
12 Authentication filters
Session settings
The settings on the Session tab enable you to configure how HTTP sessions between the HTML form client and the API Gateway are managed. Complete the following settings:
Create a session:
Select whether to create an HTTP session. This setting is selected by default.
Expiry of session in milliseconds:
Enter the period of time in milliseconds before the session expires. Defaults to 600000 (10 minutes).
Session cookie:
Enter the name of the cookie used to manage the session. The default is VIDUSR.
Session applicable for this domain:
Enter the API Gateway domain name to which the session applies (for example, dmz). Session applicable for this path:
Enter the API Gateway relative path to which the session applies. Defaults to /. Session sent over SSL only:
Select whether the session is sent over an SSL connection only. This setting is not selected by default.
HTTP Only cookie:
Select the check box to add a HTTPOnly flag to the session cookie. This is not selected by default.
Invalid login attempts settings
The settings on the Invalid Login Attempts tab enable you to specify how to handle invalid login attempts. You can choose to lock user accounts, ban IP addresses, or both, if a specified number of invalid attempts are made in a specified time period. The invalid attempt information is also stored in a cache. Note
If you are using two or more instances of HTTP basic, HTTP digest, or HTML form-based authentication filters in the same policy, and they share the same invalid attempts cache, you must use the same invalid attempts settings on each of the filters.
For more details on the settings on this tab, see Invalid attempts on page 488.
Axway API Gateway 7.5.2
Policy Developer Guide 486
12 Authentication filters
HTTP basic authentication
Overview
A client can authenticate to API Gateway with a user name and password combination using HTTP basic authentication. When an HTTP Basic Authentication filter is configured, API Gateway requests the client to present a user name and password combination as part of the HTTP basic challenge-response mechanism. API Gateway can then authenticate this user against a user profile stored in an API Gateway local repository, a database, or an LDAP directory.
With HTTP basic authentication, the client's user name and password are concatenated, base64encoded, and passed in the Authorization HTTP header as follows:
Authorization:Basic dm9yZGVsOnZvcmRlbA==
The realm presented in the challenge for HTTP basic authentication is the realm currently specified in Environment Configuration > Server Settings > General. For more details, see the API Gateway Administrator Guide.
General settings
The HTTP Basic Authentication filter enables you to specify where API Gateway finds user profiles for authentication. API Gateway can look up user profiles in an API Gateway local repository, a database, or an LDAP directory. For details on adding users to a local repository, see Manage API Gateway users on page 243.
Complete the following settings:
Name:
Enter an appropriate name for the filter to display in a policy.
Credential Format:
The user name presented to API Gateway during the HTTP basic handshake can be of many formats, usually user name or Distinguished Name (DName).Because API Gateway has no way of inherently telling one format from another (for example, the client's user name could be a DName), you must specify the format of the credential presented by the client. This format is then used internally by API Gateway when performing authorization lookups against third-party Identity Management servers.
Allow client challenge:
HTTP basic authentication can use the following approaches:
l Direct authentication: The client sends up the Authorization HTTP basic authentication header in its first request to the server. This is used mainly for machine-to-machine transactions where there is no human intervention.
Axway API Gateway 7.5.2
Policy Developer Guide 487
12 Authentication filters
l Challenge-response handshake: The client does not send the Authorization header when sending its request to the server (it does not know that the server requires HTTP basic authentication). The server responds with an HTTP 401 response code, instructing the client to authenticate to the server by sending the Authorization header. The client then sends a second request, this time including the Authorization header and the relevant user name and password. This is typical of situations where a browser is talking to a web server. When the browser receives the HTTP 401 response to its initial request, it displays a dialog to enable the user to enter the user name and password combination.
To force clients to always send the HTTP basic Authorization header to API Gateway, deselect Allow client challenge. This is selected by default to allow clients to engage in the HTTP basic authentication challenge-response handshake with API Gateway.
Allow retries:
Select this option to allow the user to retry their user name and password in the browser when an HTTP 401 response code is received (for example, if authentication fails, or is not yet provided). The number of times that the browser displays the user name and password dialog when an HTTP 401 is received is controlled by the browser (usually three times). This setting is not selected by default.
Remove HTTP authentication header:
Select this option to remove the HTTP Authorization header from the downstream message. If this option is not selected, the incoming Authorization header is forwarded on to the destination web service.
Repository Name:
Select the name of the authentication repository where all user profiles are stored. This can a local repository, a database, or an LDAP directory. You can add a new repository under the Environment Configuration > External Connections node. Right-click the appropriate node under Authentication Repositories (for example, Database Repositories), and select Add a new repository. For more details, see Configure authentication repositories on page 377.
Invalid attempts
The Invalid Attempts section enables you to specify how to handle invalid attempts. You can choose to lock user accounts, ban IP addresses, or both, if a specified number of invalid attempts are made in a specified time period. The invalid attempt information is also stored in a cache. To lock user accounts, select the Lock user accounts for check box and enter appropriate values in the corresponding fields. For example, to lock user accounts for 30 minutes if 6 invalid attempts are made over 5 minutes, you would enter the values shown in the following figure.
Axway API Gateway 7.5.2
Policy Developer Guide 488
12 Authentication filters
To ban IP addresses, select the Ban IP address after check box and enter appropriate values in the corresponding fields. For example, to ban IP addresses after 5 invalid attempts are made over 1 minute, you would enter the values shown in the preceding figure. In this case you must also enter the attribute that contains the IP address in the Key is field.
Store invalid attempt information in cache:
Click the browse button to choose a local or distributed cache to store invalid attempt information. To create a new cache right-click Caches, and select Add Local Cache or Add Distributed
Cache.
Restrictions when using the same invalid attempts cache in multiple
filters
If you configure a policy that includes two or more instances of the HTTP Basic Authentication, HTTP Digest Authentication, or HTML Form based Authentication filters that share the same cache for storing invalid attempts information, you must use the same invalid attempts settings across all filters in the policy that use this cache.
For example, if you have configured a policy that allows users to authenticate using either HTTP basic authentication or HTTP digest authentication (the policy contains one of each filter), and each of these filters uses the same cache for invalid attempts information, you must use the same invalid attempts settings on both filters to ensure that the same user logging in through the different authentication mechanisms experiences the same lockout behavior in cases where they breach the invalid attempts threshold.
HTTP digest authentication
Overview
A client can authenticate to API Gateway with a user name and password digest using HTTP digest authentication. When an HTTP Digest Authentication filter is configured, API Gateway requests the client to present a user name and password digest as part of the HTTP digest challenge-response
mechanism. API Gateway can then authenticate this user against a user profile stored in the API Gateway's local repository.
Axway API Gateway 7.5.2
Policy Developer Guide 489
12 Authentication filters
The realm presented in the challenge for HTTP digest authentication is the realm currently specified in Environment Configuration > Server Settings > General. For more information on API Gateway settings, see the API Gateway Administrator Guide.
General settings
The HTTP Digest Authentication filter enables you to specify where API Gateway can find user profiles for authentication purposes. API Gateway can look up user profiles in the API Gateway's local repository. For more information on adding users to the local repository, see Manage API Gateway users on page 243.
Complete the following settings:
Name:
Enter an appropriate name for the filter to display in a policy.
Credential Format:
The user name presented to API Gateway during the HTTP digest handshake can be of many formats, usually user name or Distinguished Name (DName). Because API Gateway has no way of inherently telling one format from another (for example, the client's user name could be a DName), you must specify the format of the credential presented by the client. This format is then used internally by API Gateway when performing authorization lookups against third-party Identity Management servers. Session Timeout:
As part of the HTTP digest authentication protocol, API Gateway must generate a nonce (number used once) value, and send it to the client. The client uses this nonce to create the digest of the user name and password. However, it should only be allowed a certain amount of time to do so. The Session Timeout field specifies the length of time (in milliseconds) for which the nonce is valid.
Allow retries:
Select this option to allow the user to retry their user name and password in the browser when an HTTP 401 response code is received (for example, if authentication fails, or is not yet provided). The number of times that the browser displays the user name and password dialog when an HTTP 401 is received is controlled by the browser (usually three times). This setting is not selected by default. Remove HTTP authentication header:
Select this option to remove the HTTP Authorization header from the downstream message. If this option is not selected, the incoming Authorization header is forwarded on to the destination web service. Repository Name:
Select the name of the local authentication repository where all user profiles are stored. You can add a new repository under the Environment Configuration > External Connections node. Right-click the Local Repositories node under Authentication Repositories, and select Add a new repository. For more details, see Configure authentication repositories on page 377.
Axway API Gateway 7.5.2
Policy Developer Guide 490
12 Authentication filters
Invalid attempts
The Invalid Attempts section enables you to specify how to handle invalid attempts. You can choose to lock user accounts, ban IP addresses, or both, if a specified number of invalid attempts are made in a specified time period. The invalid attempt information is also stored in a cache. Note
If you are using two or more instances of HTTP basic, HTTP digest, or HTML form-based authentication filters in the same policy, and they share the same invalid attempts cache, you must use the same invalid attempts settings on each of the filters.
For more details on the fields in this section, see Invalid attempts on page 488. HTTP header authentication
Overview
You can use the HTTP Header filter in cases where the API Gateway receives end user authentication credentials in an HTTP header. A typical scenario would see the end user (or message originator) authenticating to an intermediary. The intermediary authenticates the end user and, to propagate the end-user credentials to the destination web service, the intermediary inserts the credentials into an HTTP header and forwards them onwards.
When the API Gateway receives the message, it performs the following tasks:
l Authenticates the sender of the message (the intermediary)
l Extracts the end user identity from the token in the HTTP header for use in subsequent authorization filters
Note
In the case outlined above, the API Gateway does not attempt to reauthenticate the end user. It trusts that the intermediary has already authenticated the end user, and so the API Gateway does not authenticate the user again. However, it is good practice to authenticate the message sender (the intermediary). Any subsequent authorization filters use the end user credentials that were passed in the HTTP header.
Configuration
The following configuration fields are available on this window:
Name:
Enter an appropriate name for this filter to display in a policy.
HTTP Header Name:
Enter the name of the HTTP header that contains the end user credentials.
Axway API Gateway 7.5.2
Policy Developer Guide 491
12 Authentication filters
HTTP Header Type:
Select the type of credentials that are passed in the named HTTP header. The following types are supported:
l X.509 Distinguished Name
l Certificate
l User Name
IP address authentication
Overview
You can configure the API Gateway to allow or deny machines, or groups of machines, access to resources based on their IP addresses. The main table on the window shows the IP addresses from which the API Gateway accepts or denies messages depending on what is configured.
The IP Address authentication filter uses the value stored in the http.request.clientaddr message attribute to determine whether to allow or deny access. This message attribute contains the remote host address from the TCP socket used in the connection between the client and the API Gateway.
Configuration
Configure the following fields:
Name:
Enter a name for the filter to display in a policy.
IP Addresses:
You can add IP addresses by clicking the Add button, which displays the Add IP Filter dialog. Enter an IP Address and Subnet Mask to indicate a network to filter. Messages sent from hosts belonging to this network are accepted or rejected based on what is configured in the section below. A Subnet Mask of 255.255.255.255 can be used to filter specific IP addresses. For more details, see Configure subnet masks on page 493.
Note
If requests are made across a proxy, portal, or other such intermediary, the API Gateway filters on the IP address of the intermediary. Therefore, you should enter the IP address of the intermediary on this window, and not that of the user or client machine.
You can edit and remove existing IP addresses by selecting the Edit and Remove buttons.
Access:
Depending on whether the Allow Access or Deny Access radio button is checked, the IP addresses listed in the table are allowed or denied access to the web service.
Axway API Gateway 7.5.2
Policy Developer Guide 492
12 Authentication filters
Configure subnet masks
An IP address is normally represented by a string of four numbers separated by periods (for example, 192.168.0.20). Each number is normally represented as the decimal equivalent of an 8-bit binary number, which means that each number can take any value between 0 (all 8 bits cleared) and 255 (all 8 bits set).
A subnet mask (or netmask) is also a set of four number blocks separated by periods, each of which has a value in the range 0-255. Every IP address consists of two parts: the network address and the host number. The netmask is used to determine the size of these two parts. The positions of the bits set in the netmask represent the space reserved for the network address, while the bits that are cleared represent the space reserved for the host number. The netmask determines the range of IP addresses.
The following examples illustrate how netmasks work in practice.
Example 1 – Specify a range of IP addresses
To allow requests from the following IP addresses:
192.168.0.16, 192.168.0.17, 192.168.0.18, and 192.168.0.19.
Use the following address and netmask combination:
192.168.0.16/255.255.255.252
In more detail, the binary representation of the netmask is as follows:
11111111.11111111.11111111.11111100
The top 30 bits of the netmask indicate the network and the last 2 bits refer to the host on the network. These last 2 bits allow 4 different addresses as shown in the worked example below.
When the API Gateway receives a request from a certain IP address, the API Gateway performs a logical AND on the client IP address and the configured netmask. It also does a logical AND with the IP address entered in the IP Address filter and the configured subnet mask. If the AND-ed binary values are the same, the request from the IP address can be considered in the same network range as that configured in the filter. The following worked example illustrates the mechanics of the IP address filtering. It assumes that you have entered the following in the IP Address and Netmask fields in the IP Address filter:
Field
Value
IP Address
192.168.0.16
Net Mask
255.255.255.252
Axway API Gateway 7.5.2
Policy Developer Guide 493
12 Authentication filters
Step 1: AND the IP address and Netmask configured in the IP Address Filter:
11000000.10100000.00000000.00010000 (192.168.0.16)
AND
11111111.11111111.11111111.11111100 (255.255.255.252)
=========================================
11000000.10100000.00000000.00010000
Step 2: Request is received from 192.168.0.18:
11000000.10100000.00000000.00010010 (192.168.0.18)
AND
11111111.11111111.11111111.11111100 (255.255.255.252)
=========================================
11000000.10100000.00000000.00010000
===> AND-ed value is equal to the result for 192.168.0.16.
===> Therefore the client IP address is inside the configured range.
Step 3: Request is received from 192.168.0.20:
11000000.10100000.00000000.00010100 (192.168.0.20)
AND
11111111.11111111.11111111.11111100 (255.255.255.252)
=========================================
11000000.10100000.00000000.00010100
===> AND-ed value is NOT equal to the result for 192.168.0.16.
===> Therefore the client IP address is NOT inside the configured range.
Example 2 – Specify an exact IP address
You can also specify an exact IP address by using a netmask of255.255.255.255. When this netmask is used, only requests from this client IP address is allowed or blocked, depending on what is configured in the filter. This example assumes that the following details have been configured in the IP Address filter:
Field
Value
IP Address
192.168.0.36
Net Mask
255.255.255.255
Step 1: AND the IP address and Netmask configured in the IP Address Filter:
11000000.10100000.00000000.00100100 (192.168.0.36)
AND
11111111.11111111.11111111.11111111 (255.255.255.255)
=========================================
11000000.10100000.00000000.00100100
Step 2: Request is received from client with IP address of 192.168.0.37:
11000000.10100000.00000000.00100101 (192.168.0.37)
AND
11111111.11111111.11111111.11111111 (255.255.255.255)
Axway API Gateway 7.5.2
Policy Developer Guide 494
12 Authentication filters
=========================================
11000000.10100000.00000000.00100101
===> AND-ed value is NOT equal to the result for 192.168.0.36
===> Therefore the client IP address is NOT inside the configured range.
Insert SAML authentication assertion
Overview
After successfully authenticating a client, the API Gateway can insert a SAML (Security Assertion Markup Language) authentication assertion into the SOAP message. Assuming all other security filters in the policy are successful, the assertion is eventually consumed by a downstream web service.
You can refer to the following example of a signed SAML authentication assertion when configuring the Insert SAML Authentication Assertion filter:
<?xml version="1.0" encoding="UTF-8"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
<soap-env:Header xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext">
<wsse:Security>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
AssertionID="axway-1056477425082"
Id="axway-1056477425082"
IssueInstant="2003-06-24T17:57:05Z"
Issuer="CN=Sample User,....,C=IE"
MajorVersion="1"
MinorVersion="0">
<saml:Conditions
NotBefore="2003-06-20T16:20:10Z"
NotOnOrAfter="2003-06-20T18:20:10Z"/>
<saml:AuthenticationStatement
AuthenticationInstant="2003-06-24T17:57:05Z"
AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password">
<saml:SubjectLocality IPAddress="192.168.0.32"/>
<saml:Subject>
<saml:NameIdentifier
Format="urn:oasis:names:tc:SAML:1.0:assertion#X509SubjectName">
sample
</saml:NameIdentifier>
</saml:Subject>
</saml:AuthenticationStatement>
<dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"
id="Sample User">
<dsig:SignedInfo>
Axway API Gateway 7.5.2
Policy Developer Guide 495
12 Authentication filters
.....
</dsig:SignedInfo>
<dsig:SignatureValue>
rpa/......0g==
</dsig:SignatureValue>
<dsig:KeyInfo>
.....
</dsig:KeyInfo>
</dsig:Signature>
</saml:Assertion>
</wsse:Security>
</soap-env:Header>
<soap-env:Body>
<ns1:getTime xmlns:ns1="urn:timeservice">
</ns1:getTime>
</soap-env:Body>
</soap-env:Envelope>
Assertion details settings
Configure the following fields on the Assertion Details tab:
Issuer Name:
Select the certificate containing the Distinguished Name (DName) to use as the Issuer of the SAML assertion. This DName is included in the SAML assertion as the value of the Issuer attribute of the <saml:Assertion> element. For an example, see the sample SAML assertion above. Expire In:
Specify the lifetime of the assertion in this field. The lifetime of the assertion lasts from the time of insertion until the specified amount of time has elapsed.
Drift Time:
The drift time is used to account for differences in the clock times of the machine hosting the API Gateway (that generate the assertion) and the machines that consume the assertion. The specified time is subtracted from the time at which the API Gateway generates the assertion. SAML Version:
You can create SAML 1.0, 1.1, and 2.0 attribute assertions. Select the appropriate version from the list.
Note
SAML 1.0 recommends the use of the http://www.w3.org/TR/2001/REC-xmlc14n-20010315 XML Signature Canonicalization algorithm. When inserting signed SAML 1.0 assertions into XML documents, it is quite likely that subsequent signature verification of these assertions will fail. This is due to the side effect of the algorithm including inherited namespaces into canonical XML calculations of the inserted SAML assertion that were not present when the assertion was generated.
For this reason, Axway recommend that SAML 1.1 or 2.0 is used when signing assertions as they both use the exclusive canonical algorithm Axway API Gateway 7.5.2
Policy Developer Guide 496
12 Authentication filters
http://www.w3.org/2001/10/xml-exc-c14n#, which safeguards inserted assertions from such changes of context in the XML document. See section 5.4.2 of the oasis-sstc-saml-core-1.0.pdf and section 5.4.2 of sstc-saml-core1.1.pdf documents, both of which are available at http://www.oasis-open.org.
Assertion location settings
The options on the Assertion Location tab specify where the SAML assertion is inserted in the message. By default, the SAML assertion is added to the WS-Security block with the current SOAP actor/role. The following options are available:
Append to Root or SOAP Header:
Appends the SAML assertion to the message root for a non-SOAP XML message, or to the SOAP Header for a SOAP message. For example, this option may be suitable for cases where this filter may process SOAP XML messages or non-SOAP XML messages.
Add to WS-Security Block with SOAP Actor/Role:
Adds the SAML assertion to the WS-Security block with the specified SOAP actor (SOAP 1.0) or role (SOAP 1.1). By default, the assertion is added with the current SOAP actor/role only, which means the WS-Security block with no actor. You can select a specific SOAP actor/role when available from the list.
XPath Location:
To insert the SAML assertion at an arbitrary location in the message, you can use an XPath expression to specify the exact location in the message. You can select XPath expressions from the list. The default is the First WSSE Security Element, which has an XPath expression of //wsse:Security. You can add, edit, or remove expressions by clicking the relevant button. For more details, see Configure XPath expressions on page 877. You can also specify how exactly the SAML assertion is inserted using the following options:
l Append to node returned by XPath expression (the default)
l Insert before node returned by XPath expression
l Replace node returned by XPath expression
Insert into Message Attribute:
Specify a message attribute to store the SAML assertion from the drop-down list (for example, saml.assertion). Alternatively, you can also enter a custom message attribute in this field (for example, my.test.assertion). The SAML assertion can then be accessed downstream in the policy. Subject confirmation method settings
The settings on the Subject Confirmation Method tab determine how the <SubjectConfirmation> block of the SAML assertion is generated. When the assertion is Axway API Gateway 7.5.2
Policy Developer Guide 497
12 Authentication filters
consumed by a downstream web service, the information contained in the <SubjectConfirmation> block can be used to authenticate the end user that authenticated to the API Gateway, or the issuer of the assertion, depending on what is configured.
The following is a typical <SubjectConfirmation> block:
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>
urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
</saml:ConfirmationMethod>
<dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
<dsig:X509Data>
<dsig:X509SubjectName>CN=axway</dsig:X509SubjectName>
<dsig:X509Certificate>
MIICmzCCAY ...... mB9CJEw4Q=
</dsig:X509Certificate>
</dsig:X509Data>
</dsig:KeyInfo>
</saml:SubjectConfirmation>
The following configuration fields are available on the Subject Confirmation Method tab:
Method:
The selected value determines the value of the <ConfirmationMethod> element. The following table shows the available methods, their meanings, and their respective values in the <ConfirmationMethod> element:
Method
Meaning
Value
Holder Of Key
The API Gateway includes the key used to prove that the API Gateway is the holder of the key, or it includes a reference to the key.
urn:oasis:names:tc:SAML:1.0:cm:
holder-of-key
Bearer
The subject of the assertion is the bearer of the assertion.
urn:oasis:names:tc:SAML:1.0:cm:
bearer
SAML Artifact
The subject of the assertion is the user that presented a SAML Artifact to the API Gateway.
urn:oasis:names:tc:SAML:1.0:cm:
artifact
Axway API Gateway 7.5.2
Policy Developer Guide 498
12 Authentication filters
Method
Meaning
Sender Vouches
Use this confirmation method to urn:oasis:names:tc:SAML:1.0:cm:
assert that the API Gateway is bearer
acting on behalf of the authenticated end user. No other information relating to the context of the assertion is sent. It is recommended that both the assertion and the SOAP Body must be signed if this option is selected. These message parts can be signed by using the XML Signature
Generation filter (see XML signature generation on page 720).
Note
Value
You can also leave the Method field blank, in which case no <ConfirmationMethod> block is inserted into the assertion.
Holder-of-Key Configuration:
When you select Holder of Key as the SAML subject confirmation in the Method field, you must configure how information about the key is included in the message. There are a number of configuration options available depending on whether the key is a symmetric or asymmetric key.
Asymmetric Key:
To use an asymmetric key as proof that the API Gateway is the holder-of-key entity, you must select the Asymmetric Key radio button and then configure the following fields on the Asymmetric tab:
l Certificate from Store:
To select a key that is stored in the Certificate Store, select this option and click the Signing
Key button. On the Select Certificate window, select the check box next to the certificate that is associated with the key to use. l Certificate from Selector Expression:
Alternatively, the key may have already been used by a previous filter in the policy (for example, to sign a part of the message). In this case, the key can be retrieved using the selector expression entered in this field. Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, Key Property Store, or environment variable). For more details, see Select configuration values at runtime on page 854.
Symmetric Key:
To use a symmetric key as proof that the API Gateway is the holder of key, select the Symmetric
Key radio button, and configure the fields on the Symmetric tab:
l Generate Symmetric Key, and Save in Message Attribute:
If you select this option, the API Gateway generates a symmetric key, which is included in the message before it is sent to the client. By default, the key is saved in the symmetric.key message attribute. Axway API Gateway 7.5.2
Policy Developer Guide 499
12 Authentication filters
l Symmetric Key Selector Expression:
If a previous filter (for example, an XML Signature Generation filter) has already used a symmetric key, you can reuse this key as proof that the API Gateway is the holder-of-key entity. Enter the name of the selector expression (for example, message attribute) in the field provided, which defaults to ${symmetric.key}. Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, Key Property Store, or environment variable). For more details, see Select configuration values at runtime on page 854.
l Encrypt using Certificate from Certificate Store:
When a symmetric key is used, you must assume that the recipient has no prior knowledge of this key. It must, therefore, be included in the message so that the recipient can validate the key. To avoid meet-in-the-middle style attacks, where a hacker could eavesdrop on the communication channel between the API Gateway and the recipient and gain access to the symmetric key, the key must be encrypted so that only the recipient can decrypt the key. One way of doing this is to select the recipient's certificate from the Certificate Store. By encrypting the symmetric key with the public in the recipient's certificate, the key can only be decrypted by the recipient's private key, to which only the recipient has access. Select the Signing Key button, and select the recipient's certificate on the Select Certificate dialog.
l Encrypt using Certificate from Selector Expression:
Alternatively, if the recipient's certificate has already been used (perhaps to encrypt part of the message), the certificate can be retrieved using the selector expression entered in this field. Using a selector enables settings to be evaluated and expanded at runtime based on metadata (for example, in a message attribute, Key Property Store, or environment variable). For more details, see Select configuration values at runtime on page 854.
l Symmetric Key Length:
Enter the length (in bits) of the symmetric key to use.
l Key Wrap Algorithm:
Select the algorithm to use to encrypt ( wrap ) the symmetric key.
Key Info:
The Key Info tab must be configured regardless of whether you have elected to use symmetric or asymmetric keys. It determines how the key is included in the message. The following options are available:
l Do Not Include Key Info:
Select this option if you do not wish to include a <KeyInfo>section in the SAML assertion.
l Embed Public Key Information:
If this option is selected, details about the key are included in a <KeyInfo> block in the message. You can include the full certificate, expand the public key, include the distinguished name, and include a key name in the <KeyInfo> block by selecting the appropriate check boxes. When selecting the Include Key Name field, you must enter a name in the Value field, and then select the Text Value or Distinguished Name Attribute radio button, depending on the source of the key name. Axway API Gateway 7.5.2
Policy Developer Guide 500
12 Authentication filters
l Put Certificate in Attachment:
Select this option to add the certificate as an attachment to the message. The certificate is then referenced from the <KeyInfo> block. l Security Token Reference:
The Security Token Reference (STR) provides a way to refer to a key contained within a SOAP message from another part of the message. It is often used in cases where different security blocks in a message use the same key material and it is considered an overhead to include the key more than once in the message. When this option is selected, a <wsse:SecurityTokenReference> element is inserted into the <KeyInfo> block. It references the key material using a URI to point to the key material and a ValueType attribute to indicate the type of reference used. For example, if the STR refers to an encrypted key, you should select EncryptedKey from the list, whereas if it refers to a BinarySecurityToken, you should select X509v3 from the list. Other options are available to enable more specific security requirements.
Advanced settings
The settings on the Advanced tab include the following fields.
Select Required Layout Type:
WS-Policy and SOAP Message Security define a set of rules that determine the layout of security elements that appear in the WS-Security header within a SOAP message. The SAML assertion is inserted into the WS-Security header according to the layout option selected here. The available options correspond to the WS-Policy Layout assertions of Strict, Lax, LaxTimestampFirst, and LaxTimestampLast.
Insert SAML Attribute Statement:
You can insert a SAML attribute statement into the generated SAML authentication assertion. If you select this option, a SAML attribute assertion is generated using attributes stored in the attribute.lookup.list message attribute and subsequently inserted into the assertion. The attribute.lookup.list attribute must have been populated previously by an attribute lookup filter for the attribute statement to be generated successfully.
Indent:
Select this method to ensure that the generated signature is properly indented.
Security Token Reference:
The generated SAML authentication assertion can be encapsulated within a <SecurityTokenReference> block. The following example demonstrates this:
<soap:Header>
<wsse:Security
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext"
soap:actor="axway">
<wsse:SecurityTokenReference>
Axway API Gateway 7.5.2
Policy Developer Guide 501
12 Authentication filters
<wsse:Embedded>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
AssertionID="Id-00000109fee52b06-0000000000000012"
IssueInstant="2006-03-15T17:12:45Z"
Issuer="axway" MajorVersion="1" MinorVersion="0">
<saml:Conditions NotBefore="2006-03-15T17:12:39Z"
NotOnOrAfter="2006-03-25T17:12:39Z"/>
<saml:AuthenticationStatement
AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"
AuthenticationInstant="2006-03-15T17:12:45Z">
<saml:Subject>
<saml:NameIdentifier Format="Axway-Username-Password">
admin
</saml:NameIdentifier>
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>
urn:oasis:names:tc:SAML:1.0:cm:artifact
</saml:ConfirmationMethod>
</saml:SubjectConfirmation>
</saml:Subject>
</saml:AuthenticationStatement>
</saml:Assertion>
</wsse:Embedded>
</wsse:SecurityTokenReference>
</wsse:Security>
</soap:Header>
To add the SAML assertion to a <SecurityTokenReference> block as in the example above, select the Embed SAML assertion within Security Token Reference option. Otherwise, select No Security Token Reference.
Insert timestamp
Overview
In any secure communications protocol, it is crucial that secured messages do not have an indefinite life span. In secure web services transactions, a WS-Utility (WSU) timestamp can be inserted into a WS-Security Header to define the lifetime of the message in which it is placed. A message containing an expired timestamp should be rejected immediately by any web service that consumes the message. Typically, the timestamp contains Created and Expires times, which combine to define the lifetime of the timestamp. The following shows an example wsu:Timestamp:
<wsu:Timestamp xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wsu:Created>2009-03-16T16:32:22Z</wsu:Created>
Axway API Gateway 7.5.2
Policy Developer Guide 502
12 Authentication filters
<wsu:Expires>2009-03-16T16:42:22Z</wsu:Expires>
</wsu:Timestamp>
Because the WS-Utility timestamp is inserted into the WS-Security header block, it is also referred to as a WSS timestamp. For example, see Extract WSS timestamp on page 441.
Configuration
Complete the following fields to configure the API Gateway to insert a timestamp into the message:
Name:
Enter an intuitive name for the filter to display in a policy.
Actor:
The timestamp is inserted into the WS-Security header identified by the SOAP Actor selected here.
Expires In:
Configure the lifetime of the timestamp (and hence the message into which the timestamp is inserted) by specifying the expiry time of the assertion. The expiry time is expressed in days, hours, minutes, and seconds. Layout Type:
In cases where the timestamp must adhere to a particular layout as mandated by the WS-Policy <Layout> assertion, you must select the appropriate layout type. A web service that enforces a WS-Policy might reject the message if the layout of security elements in the SOAP header is incorrect. Therefore, you must ensure that you select the correct layout type.
Insert WS-Security UsernameToken
Overview
When a client has been successfully authenticated, the API Gateway can insert a WS-Security UsernameToken into the downstream message as proof of the authentication event. The <wsse:UsernameToken> token enables a user's identity to be inserted into the XML message so that it can be propagated over a chain of web services.
A typical example would see a user authenticating to the API Gateway using HTTP digest authentication. After successfully authenticating the user, the API Gateway inserts a WS-Security UsernameToken into the message and digitally signs it to prevent anyone from tampering with the token.
The following example shows the format of the <wsse:UsernameToken> token:
<wsse:UsernameToken wsu:Id="axway"
Axway API Gateway 7.5.2
Policy Developer Guide 503
12 Authentication filters
xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility">
<wsu:Created>2006.01.13T-10:42:43Z</wsu:Created>
<wsse:Username>axway</wsse:Username>
<wsse:Nonce EncodingType="UTF-8">
KFIy9LgzhmDPNiqU/B9ZiWKXfEVNvFyn6KWYP+1zVt8=
</wsse:Nonce>
<wsse:Password Type="wsse:PasswordDigest">
CxWj1OMnYj7dddMnU/DrOhyY3j4=
</wsse:Password>
</wsse:UsernameToken>
This topic explains how to configure the API Gateway to insert a WS-Security UsernameToken after successfully authenticating a user.
General settings
To configure general settings, complete the following fields:
Name:
Enter an appropriate name for the filter to display in a policy.
Actor:
The UsernameToken is inserted into the WS-Security block identified by the specified SOAP Actor. Credential details
To configure the credential details, complete the following fields:
Username:
Enter the name of the user included in the UsernameToken. By default, the authentication.subject.id message attribute is stored, which contains the name of an authenticated user.
Include Nonce:
Select this option to include a nonce in the UsernameToken. A nonce is a random number that is typically used to help prevent replay attacks.
Include Password:
Select this option if you wish to include a password in the UsernameToken.
Password:
If the Include Password check box is selected, the API Gateway inserts the user's password into the generated WS-Security UsernameToken. It can insert a Clear or SHA1 Digest version of the password, depending on which radio button you select. Axway recommends the digest form of the password to avoid potential eavesdropping.
Axway API Gateway 7.5.2
Policy Developer Guide 504
12 Authentication filters
You can either explicitly enter the password for this user in the Password field, or use a message attribute by selecting the Wildcard option, and entering the message attribute selector in the field provided. The default is ${authentication.subject.password}, which contains the user password to authenticate to the API Gateway.
Advanced options
To configure advanced options, complete the following field:
Indent:
Select this option to add indentation to the generated UsernameToken and Signature blocks. This makes the security tokens more human-readable.
Kerberos client authentication
Overview
You can configure the API Gateway to act as a Kerberos client and to obtain a service ticket for a specific Kerberos service. The service ticket makes up part of the Kerberos client-side token that is sent to the Kerberos service. If the service can validate the token, the client is authenticated successfully.
For more details on different Kerberos setups with API Gateway, see API Gateway Kerberos Integration Guide.
There are two filters you can use to configure the client-side transaction:
l Use a Connection filter to authenticate to a Kerberos service by inserting a client-side Kerberos token into the Authorization HTTP header. For more information on authenticating to a Kerberos service using a client-side Kerberos token, see Connection on page 786.
l Use a Kerberos Client filter to send the client-side Kerberos token in a BinarySecurityToken block in the SOAP message. To add a Kerberos Client filter, open the Authentication category, and drag the filter onto the policy canvas. The following sections describe how to configure the different fields of this filter.
Kerberos client settings
The fields configured on the Kerberos Client tab determine how the Kerberos client obtains a service ticket for a specific Kerberos service. Configure the following fields:
Axway API Gateway 7.5.2
Policy Developer Guide 505
12 Authentication filters
Kerberos Client:
The role of the Kerberos client selected in this field is twofold. First, it must obtain a Kerberos Ticket Granting Ticket (TGT) and second, it uses this TGT to obtain a service ticket for the selected Kerberos Service Principal. The TGT is acquired at server startup, server refresh (for example, when an update to configuration is deployed), and when the TGT expires. To select which Kerberos client to use, click the ... button, and select a previously configured Kerberos client. To add a Kerberos client, right-click Kerberos Clients, and select Add Kerberos
Client. You can also add Kerberos clients under Environment Configuration > External
Connections in the node tree. For more details, see Configure Kerberos clients on page 407.
Kerberos Service Principal:
The Kerberos client must obtain a service ticket from the Kerberos Ticket Granting Server (TGS) for the Kerberos service principal you set in this field. The TGS grants the Kerberos client a ticket for the selected principal, and the client can then send this ticket to the Kerberos service. The principal in the ticket must match the Kerberos service's principal for the client to be successfully authenticated. The service principal name (SPN) can be used to uniquely identify the Kerberos service in the Kerberos realm.
To select which Kerberos service principal to use, click the ... button on the right, and select a previously configured Kerberos principal in the tree (for example, the default HTTP/host
Service Principal). To add a Kerberos principal, right-click Kerberos Principals, and select Add Kerberos Principal. You can also add Kerberos principals under Environment
Configuration > External Connections in the node tree. For more details, see Configure Kerberos principals on page 412.
Kerberos Standard:
When using the Kerberos Client filter to insert Kerberos tokens into SOAP messages, the Kerberos client can authenticate to Kerberos services using to two standards:
l Web Services Security Kerberos Token Profile 1.1 – When using the Kerberos Token Profile, the client-side Kerberos token is inserted into a BinarySecurityToken block in the SOAP message. If you select this option, you must configure the fields on the Kerberos Token
Profile tab. You can use signing and encryption filters to sign and encrypt the SOAP message using the Kerberos session key. l WS-Trust for Simple and Protected Negotiation Protocol (SPNEGO) – When using the WS-Trust for SPNEGO standard, a series of requests and responses occur between the Kerberos client and the Kerberos service to establish a secure context using WS-Trust and WSSecureConversation. After establishing the secure context, a further series of requests and responses produce a shared secret key that can be used to sign and encrypt real requests to the Kerberos service.If you select this option, it is not necessary to configure the fields on the Kerberos Token Profile tab, but you must configure the Kerberos Client filter as a part of a complicated policy set up to handle the multiple request and response messages involved in establishing the secure context between the Kerberos client and service.
Axway API Gateway 7.5.2
Policy Developer Guide 506
12 Authentication filters
Kerberos token profile settings
You only need to configure the fields on the Kerberos Token Profile tab if you set Kerberos
Standard to Web Services Security Kerberos Token Profile 1.1 on the Kerberos Client tab. This tab allows you to configure where to insert the BinarySecurityToken in the SOAP message. Where to Place BinarySecurityToken:
You can insert the BinarySecurityToken inside a named WS-Security Actor/Role in the SOAP message, or you can specify an XPath expression to indicate where the token should be inserted. To insert the token into a WS-Security element in the SOAP Header element, select WS-Security
Element. The BinarySecurityToken is inserted into a WS-Security block for the specified actor/role. You can use the default option Current actor/role only, or enter a named actor/role in the field provided.
Alternatively, to use an XPath expression to specify where to insert the BinarySecurityToken, select XPath Location. Click the Add button to add a new XPath expression, or select an existing XPath expression from the list. You can also edit or delete existing expressions, if needed. For more information, see Configure XPath expressions on page 877.
Note
You can control inserting the BinarySecurityToken relative to the node pointed to by the XPath expression. Select the Append to insert the token after or Before to insert the token before the node. BinarySecurityToken Value Type:
Currently, the only supported BinarySecurityToken type is GSS_Kerberosv5_AP_REQ. The selected type is specified in the generated BinarySecurityToken. Kerberos service authentication
Overview
The API Gateway can act as a Kerberos service to consume Kerberos tokens sent from a client in the HTTP header or in the message itself. The Kerberos client must have obtained a ticket from the Ticket Granting Server (TGS) for this Kerberos service. The service ticket makes up part of the Kerberos client-side token that is sent to the Kerberos service. If the service can validate the token, the client is authenticated successfully.
For more details on different Kerberos setups with API Gateway, see API Gateway Kerberos Integration Guide.
To add a Kerberos Service filter, open the Authentication category, and drag the filter onto the policy canvas. The following sections describe how to configure the different fields of this filter.
Axway API Gateway 7.5.2
Policy Developer Guide 507
12 Authentication filters
General settings
The fields configured on the Kerberos Client tab determine how the Kerberos service consumes a Kerberos token from a specific Kerberos client. Configure the following fields:
Kerberos Service:
The Kerberos Service you select in this field is responsible for consuming the Kerberos client's Kerberos token. The Kerberos client must have obtained a ticket for the Kerberos service's principal name to be able to authenticate to the Kerberos service.
Click the ... button, and select a previously configured Kerberos service. To add a Kerberos service, right-click Kerberos Services, and select Add Kerberos Service. You can also add Kerberos services under Environment Configuration > External Connections in the node tree. For more details, see Configure Kerberos services on page 414.
Kerberos standard settings
Configure the following fields o n the Kerberos Standard tab:
Kerberos Standard:
Select one of the following Kerberos standards:
l Kerberos Token Profile
l WS-Trust for SPNEGO
l SPNEGO over HTTP
Note
The Kerberos Service filter consumes the Kerberos client-side tokens regardless of whether the token is sent at the message layer in the SOAP message, or at the transport layer in an HTTP header. Client Token Location for Message-Level Standards:
The Kerberos service ticket can be sent in the Authorization HTTP header, or inside the message itself (for example, inside a <BinarySecurityToken> element). Alternatively, the Kerberos token can be in a message attribute. Select one of the following options:
l Message Body:
Select this option if you expect the Kerberos service ticket to be contained in the message. You must enter an XPath expression to point to the expected location of the Kerberos token. You can select some default expressions that point to common locations from the list. To add a new XPath expression, click Add. You can also edit or delete existing expressions, if needed. For more details, see Configure XPath expressions on page 877.
l Selector Expression:
When using the WS-Trust for SPNEGO standard, the Consume WS-Trust filter places the client-side Kerberos token inside the ws.trust.spnego.token message attribute. Axway API Gateway 7.5.2
Policy Developer Guide 508
12 Authentication filters
Message level settings
You can configure settings adhering to the message-level standards (for example, Kerberos Token Profile and WS-Trust for SPNEGO) on the Message Level tab. Extract Session Keys:
You must select this option to use the Kerberos/SPNEGO session keys to sign, encrypt, or decrypt a message in a subsequent filter. This option is only available when the token is extracted from the message body.
Key Length:
When using WS-Trust for SPNEGO standard, the Kerberos Service filter generates a new symmetric key and wraps it using the Kerberos session key. This setting determines the length of the new symmetric key. Cache Security Context Session Key:
The service-side policy might need to cache the session key in order to process (decrypt and verify) multiple requests from a Kerberos client. Use this field to select a cache for the session key.
Transport level settings
The options on the Transport Level tab are specific to Kerberos tokens received over HTTP, and are only relevant if you selected to use SPNEGO Over HTTP standard.
Cookie Name:
The initial handshake between a Kerberos client and a Kerberos service can sometimes involve the exchange of a series of request and responses until the secure context has been established. In such cases, you can use a HTTP cookie to keep track of the context across multiple request and response messages. Enter the name of the cookie in the text field. Allow Client Challenge:
In some cases, a Kerberos client might not authenticate (send the Authorization HTTP header) to the Kerberos service on first request. The Kerberos service then responds with an HTTP 401 response code, instructing the client to authenticate to the server by sending the Authorization header. The Kerberos client sends a second request, this time with the Authorization header containing the relevant Kerberos token. Select this option to allow this kind of negotiation between the Kerberos client and service.
Client Sends Body Only After Context is Established:
The Kerberos client might wait to mutually authenticate the Kerberos service before sending the body of the message. Select this option to enable the Kerberos service to accept the body after the context has been established if the Kerberos client provides the known cookie. The cookies are cached in the cache you configure.
Advanced SPNEGO settings
The settings o n the Advanced SPNEGO tab apply only to the WS-Trust for SPENGO and SPENGO over HTTP standards.
Axway API Gateway 7.5.2
Policy Developer Guide 509
12 Authentication filters
Cache Partially Established Contexts:
In theory, a Kerberos client and a Kerberos service may need to send and receive a number of tokens between each other to authenticate. In this case, the Kerberos Service filter must cache the partially established context for each Kerberos client. The contexts are only cached during the establishment of the context. In practice, however, a single client-side Kerberos token is normally enough to establish a context on the service-side, making this setting redundant. SAML authentication
Overview
A Security Assertion Markup Language (SAML) authentication assertion is issued as proof of an authentication event. Typically, an end user authenticates to an intermediary, who generates a SAML authentication assertion to prove that it has authenticated the user. The intermediary inserts the assertion into the message for consumption by a downstream web service.
When the API Gateway receives a message containing a SAML authentication assertion, it does not attempt to authenticate the end user again. Instead, it authenticates the sender of the assertion (the intermediary) to ensure that only the intermediary could have issued the assertion, and then validates the authentication details contained in the assertion. Therefore, the API Gateway performs the following tasks in this scenario:
l Authenticates the sender of the message (the intermediary)
l Extracts the end user's identity from the authentication assertion and validates the authentication details
The SAML Authentication filter performs the second task. A separate authentication filter must be placed before this filter in the policy to authenticate the sender of the assertion. The end user's identity is used in any subsequent authorization filters.
The following sample SOAP message contains a SAML authentication assertion:
<?xml version="1.0" encoding="UTF-8"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
<soap-env:Header xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext">
<wsse:Security>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
AssertionID="axway-1056477425082"
Id="axway-1056477425082"
IssueInstant="2003-06-24T17:57:05Z"
Issuer="CN=Sample User,....,C=IE"
MajorVersion="1"
MinorVersion="0">
Axway API Gateway 7.5.2
Policy Developer Guide 510
12 Authentication filters
<saml:Conditions
NotBefore="2003-06-20T16:20:10Z"
NotOnOrAfter="2003-06-20T18:20:10Z"/>
<saml:AuthenticationStatement
AuthenticationInstant="2003-06-24T17:57:05Z"
AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password">
<saml:SubjectLocality IPAddress="192.168.0.32"/>
<saml:Subject>
<saml:NameIdentifier
Format="urn:oasis:names:tc:SAML:1.0:assertion#X509SubjectName">
sample
</saml:NameIdentifier>
</saml:Subject>
</saml:AuthenticationStatement>
<dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"
id="Sample User">
<dsig:SignedInfo>
.....
</dsig:SignedInfo>
<dsig:SignatureValue>
rpa/......0g==
</dsig:SignatureValue>
<dsig:KeyInfo>
.....
</dsig:KeyInfo>
</dsig:Signature>
</saml:Assertion>
</wsse:Security>
</soap-env:Header>
<soap-env:Body>
<ns1:getTime xmlns:ns1="urn:timeservice">
</ns1:getTime>
</soap-env:Body>
</soap-env:Envelope>
Details settings
Configure the following fields on the Details tab:
SOAP Actor/Role:
If you expect the SAML assertion to be embedded in a WS-Security block, you can identify this block by specifying the SOAP Actor or Role of the WS-Security header that contains the assertion.
XPath Expression:
Alternatively, if the assertion is not contained in a WS-Security block, you can enter an XPath expression to locate the authentication assertion. You can configure XPath expressions using the Add, Edit, and Delete buttons.
Axway API Gateway 7.5.2
Policy Developer Guide 511
12 Authentication filters
SAML Namespace:
Select the SAML namespace that must be used on the SAML assertion for this filter to succeed. If you do not wish to check the namespace, select the Do not check version option from the list.
SAML Version:
Specify the SAML version that the assertion must adhere to by entering the major version in the first field, and the minor version in the second field. For example, for SAML 2.0, enter 2 in the first field and 0 in the second field.
Drift Time:
The drift time, specified in seconds, is used when checking the validity dates on the authentication assertion. The drift time allows for differences between the clock times of the machine on which the assertion was generated and the machine hosting the API Gateway.
Remove enclosing WS-Security element on successful validation:
Select this check box to remove the WS-Security block that contains the SAML assertion after the assertion has been successfully validated.
Trusted issuer settings
You can use the table on the Trusted Issuers tab to select the issuers that you consider trusted. In other words, this filter only accepts assertions that have been issued by the SAML authorities selected here. Click the Add button to display the Trusted Issuers window. Select the Distinguished Name of a SAML authority whose certificate has been added to the certificate store, and click OK. Repeat this step to add more SAML authorities to the list of trusted issuers.
SAML PDP authentication
Overview
The API Gateway can request an authentication decision from a Security Assertion Markup Language (SAML) Policy Decision Point (PDP) for an authenticated client using the SAML Protocol (SAMLP). In such cases, the API Gateway presents evidence to the PDP in the form of some user credentials, such as the Distinguished Name of a client's X.509 certificate. The PDP decides whether to authenticate the end user. It then creates an authentication assertion, signs it, and returns it to the API Gateway in a SAMLP response. The API Gateway can then perform a number of checks on the response, such as validating the PDP signature and certificate, and examining the assertion. It can also insert the SAML authentication assertion into the message for consumption by a downstream web service.
Axway API Gateway 7.5.2
Policy Developer Guide 512
12 Authentication filters
Request settings
The Request tab describes how the API Gateway should package the SAMLP request before sending it to the SAML PDP.
You can configure the following fields on the Request tab:
SAML PDP URL Set:
You can configure a group of SAML PDPs to which the API Gateway connects in a round-robin fashion if one or more of the PDPs are unavailable. This is known as a SAML PDP URL set. Click the button on the right, and select a previously configured SAML PDP URL set in the tree. To add a URL set, right-click the SAML PDP URL Sets tree node, and select Add a URL Set. Alternatively, you can configure a SAML PDP URL set under the Environment Configuration > External
Connections node in the Policy Studio tree.
SOAP Action:
Enter the SOAP action required to send SAMLP requests to the PDP. Click the Use Default button to use the following default SOAP action as specified by SAMLP:
http://www.oasis-open.org/committees/security
SAML Version:
Select the SAML version to use in the SAMLP request.
Signing Key:
If the SAMLP request is to be signed, click the Signing Key button, and select the appropriate signing key from the certificate store.
SAML subject settings
You can describe the subject of the SAML assertion on the SAML Subject tab. Complete the following fields:
Subject Selector Expression:
Enter a selector expression for the message attribute that contains the user name of an authenticated user. The default value is ${authentication.subject.id}.
Subject Format:
Select the format of the subject selected in the Subject Selector Expression field above. Note
There is no need to select a format here if the Subject Selector Expression field is set to authentication.subject.id.
Axway API Gateway 7.5.2
Policy Developer Guide 513
12 Authentication filters
Subject confirmation settings
The settings on the Subject Confirmation tab determine how the <SubjectConfirmation>
block of the SAML assertion is generated. When the assertion is consumed by a downstream web service, the information contained in the <SubjectConfirmation> block can be used to authenticate the end user that authenticated to the API Gateway, or the issuer of the assertion, depending on what is configured.
The following is a typical <SubjectConfirmation> block:
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>
urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
</saml:ConfirmationMethod>
<dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
<dsig:X509Data>
<dsig:X509SubjectName>CN=axway</dsig:X509SubjectName>
<dsig:X509Certificate>
MIICmzCCAY ...... mB9CJEw4Q=
</dsig:X509Certificate>
</dsig:X509Data>
</dsig:KeyInfo>
</saml:SubjectConfirmation>
You must configure the following fields on the Subject Confirmation tab:
Method:
The selected value determines the value of the <ConfirmationMethod> element. The following table shows the available methods, their meanings, and their respective values in the <ConfirmationMethod> element:
Axway API Gateway 7.5.2
Policy Developer Guide 514
12 Authentication filters
Metho
d
Meaning
Value
Holder Of Key
A <SubjectConfirmation> is urn:oasis:names:tc:SAML:1.0:c
inserted into the SAMLP request. The m:
<SubjectConfirmation> holder-of-key
contains a <dsig:KeyInfo> section with the certificate of the user selected to sign the SAMLP request. The user selected to sign the SAMLP request must be the authenticated subject (
authentication.subject.i
d).
Select the Include Certificate option if the signer's certificate is to be included in the SubjectConfirmation block. Alternatively, select the Include
Key Name option if only the key name is to be included. Bearer
A <SubjectConfirmation> is urn:oasis:names:tc:SAML:1.0:c
inserted into the SAMLP request.
m:
bearer
SAML Artifact
A <SubjectConfirmation> is urn:oasis:names:tc:SAML:1.0:c
inserted into the SAMLP request.
m:
artifact
Sender Vouche
s
A <SubjectConfirmation> is urn:oasis:names:tc:SAML:1.0:c
inserted into the SAMLP request. The m:
SAMLP request must be signed by a bearer
user. If the Method field is left blank, no <ConfirmationMethod> block is inserted into the assertion.
Include Certificate:
Select this option to include the SAML subject's certificate in the <KeyInfo> section of the <SubjectConfirmation> block.
Include Key Name:
Alternatively, to not include the certificate, select this option to only include the key name in the <KeyInfo> section.
Axway API Gateway 7.5.2
Policy Developer Guide 515
12 Authentication filters
Response settings
The Response tab configures the SAMLP response returned from the SAML PDP. The following fields are available:
SOAP Actor/Role:
If the SAMLP response from the PDP contains a SAML authentication assertion, the API Gateway can extract it from the response and insert it into the downstream message. The SAML assertion is inserted into the WS-Security block identified by the specified SOAP actor/role. Drift Time:
The SAMLP request to the PDP is time stamped by the API Gateway. To account for differences in the times on the machines running the API Gateway and the SAML PDP the specified time is subtracted from the time at which the API Gateway generates the SAMLP request.
SSL authentication
Overview
A client can mutually authenticate to the API Gateway through the exchange of X.509 certificates. An X.509 certificate contains identity information about its owner and is digitally signed by the Certificate Authority (CA) that issued it. A client presents such a certificate to the API Gateway while the initial SSL/TLS session is being negotiated, in other words, during the SSL handshake. The SSL Authentication filter extracts this information from the client certificate and sets it as message attributes. These attributes can then be used by subsequent filters in the policy.
The SSL Authentication filter can be used as a decision-making node on the policy. For example, it can be used to determine a path through a policy based on how users authenticate to the API Gateway.
STS client authentication
Overview
The Security Token Service Client filter enables the API Gateway to act as a client to a Security Token Service (STS). An STS is a third-party web service that authenticates clients by validating credentials and issuing security tokens across different formats (for example, SAML, Kerberos, or X.509). The API Gateway can use the Security Token Service Client filter to request security tokens from an STS using WS-Trust. WS-Trust specifies the protocol for issuing, exchanging, and validating security tokens. Axway API Gateway 7.5.2
Policy Developer Guide 516
12 Authentication filters
An STS has its own security requirements for authenticating and authorizing requests for tokens. This means that the API Gateway might need to insert tokens, digitally sign, and encrypt the request that it sends to the STS for the required token. Because the STS is exposed as a web service, it should have a WSDL file with WS-Policies that describe its security requirements.
For example, the API Gateway can use the Security Token Service Client filter to request tokens that it cannot issue itself, and which might be required by an endpoint service. The endpoint service might require tokens to be signed by a particular authority (STS), or there might be a requirement for a token that contains a key encrypted for the endpoint service, and which only the STS can generate. You can also use the S ecurity Token Service Client filter to virtualize an STS using the API Gateway. Example request
Using WS-Trust, requests for tokens are placed in a RequestSecurityToken (RST) element in the SOAP Body element. The STS returns the requested token in a RequestSecurityTokenResponse (RSTR) element in the SOAP Body. The following example is an extract from a token request message sent from the API Gateway to the STS:
<soap:Body
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd"
wsu:Id="Id-0000012e71431904-00000000011d5641-19">
<wst:RequestSecurityToken
xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
Context="Id-0000012e71431904-00000000011d5641-15">
<wst:RequestType>
http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
</wst:RequestType>
<wst:TokenType>
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
</wst:TokenType>
<wst:KeyType>
http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
</wst:KeyType>
<wst:Entropy>
<wst:BinarySecret
Type="http://schemas.xmlsoap.org/ws/2005/02/trust/SymmetricKey">
WLQmo5mRYiBRqq2D7677Dg==
</wst:BinarySecret>
</wst:Entropy>
<wsp:AppliesTo
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsa:EndpointReference
xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>default</wsa:Address>
</wsa:EndpointReference>
</wsp:AppliesTo>
</wst:RequestSecurityToken>
Axway API Gateway 7.5.2
Policy Developer Guide 517
12 Authentication filters
</soap:Body>
In this simple example, the client (API Gateway) requests a SAML token with a symmetric KeyType. The SAML token is requested for an endpoint service named default. An optional OnBehalfOf token is not supplied.
Request settings
Configure the following general request settings on the Request tab:
Request Type:
Select one of the following request types:
l Issue: A request to issue a token. This is the default request type.
l Validate: A request to validate a token.
Token Type to Request:
Select the token type to request from the STS (for example, SAML 1.0, SAML 1.1, SAML 2.0, or UsernameToken). You can also request a custom token type by entering the custom token URI (for example, http://www.mycustomtoken.com/EmailToken). The default is SAML
1.1.
Issue: POP Key
A proof-of-possession (POP) security token contains secret data used to demonstrate authorized use of an associated security token. Typically, the POP data is encrypted with a key known only to the recipient of the POP token. For Issue requests, you can configure the following POP key settings on the Issue: POP Key tab:
Proof of Possession Key Type:
Select the POP key type for the token you are requesting. This only applies to certain types of tokens (for example, SAML tokens). Select one of the following key types from the list:
Axway API Gateway 7.5.2
Policy Developer Guide 518
12 Authentication filters
SymmetricKey
When a SAML token is requested with a symmetric POP key, the SAML assertion returned by the STS has a subject confirmation type of holderof-key. The subject confirmation data contains a symmetric key encrypted for the endpoint service. The API Gateway (the client) can request the SAML token from the STS with the endpoint service specified as the token scope, so the STS knows what certificate to use to encrypt the symmetric key it places in the SAML assertion’s subject confirmation data. The API Gateway cannot decrypt the symmetric key in the SAML assertion because it is encrypted for the endpoint service. The STS passes the symmetric key to the requesting API Gateway in the RSTR so that the API Gateway also has the symmetric key. It can then use the SAML assertion (symmetric key) to sign the message to the endpoint service, proving that it holds the key in the SAML assertion. The endpoint service can verify the signature because it can decrypt the key in the SAML assertion. This is the default POP key type.
PublicKey
When a SAML token is requested with a public asymmetric POP key, the SAML assertion returned by the STS has a subject confirmation type of holder-of-key. The subject confirmation data contains a public key or certificate. The API Gateway (the client) can also use this SAML assertion to sign messages to the endpoint service using the related private key, thus proving they hold the key referenced in the SAML assertion. The public key in the SAML assertion is not encrypted because it is not sensitive data. This SAML assertion can be used to sign messages to multiple endpoint services because it does not contain a key encrypted for a specific service. The API Gateway can specify the public key used in the Public Proof of
Possession Key settings. This public key can be associated with a certificate in the certificate store, or generated on-the-fly using the Generate Key filter. For more details, see Generate key on page 669.
Bearer
When a SAML token is requested with a bearer POP key, the SAML assertion returned by the STS has a subject confirmation type of bearer. In this case, the SAML token does not contain a POP key. Note
An STS can also generate a SAML token with a subject confirmation type of sendervouches. In this case, the endpoint service trusts the client directly, the SAML assertion does not need to be signed by the STS. The client signs the SAML assertion and the SOAP Body before sending the message to the endpoint service. This type of SAML assertion does not map to a value for Proof of Possession Key Type, but can be returned from the STS if no key type is specified. Key Size:
Enter the key size in bits to indicate the desired strength of the security. Defaults to 256 bits.
Entropy Type:
If the Proof of Possession Key Type requested is a SymmetricKey, you must specify an Entropy Type. If the API Gateway provides entropy, this means that it provides some of the binary Axway API Gateway 7.5.2
Policy Developer Guide 519
12 Authentication filters
material used to generate the symmetric key. In general, both the API Gateway and the STS provide some entropy for the symmetric key (a computed key). However, either side can also fully generate the symmetric key. Select one of the following options:
l None: The API Gateway does not provide any entropy, so the STS must fully generate the symmetric key.
l Binary Secret: The API Gateway provides entropy in the form of a Base64-encoded binary secret (or key). You must specify a Binary Secret Type. For details, see the next setting.
l Encrypted Key: The API Gateway provides entropy in the form of an EncryptedKey element. You must configure an XML-Encryption filter in the policy, which applies security before creating the WS-Trust message. This filter generates a symmetric key and encrypts it, but does not encrypt any data. The key must be encrypted with the STS certificate.
Binary Secret Type:
If the Entropy Type is Binary Secret, you must specify a Binary Secret Type. Select one of the following:
l Nonce: The API Gateway generates a nonce value and places it in the RST.
l SymmetricKey: The Binary Secret Message Attribute value must be specified. In this case, this is the name of the message attribute that contains the symmetric key passed to the STS to be used as entropy for generating the POP symmetric key. The type of this message attribute must be byte[] when the Binary Secret Type is SymmetricKey.
l AsymmetricKey: The Binary Secret Message Attribute value must be specified. In this case, this is the name of the message attribute that contains the private asymmetric key passed to the STS to be used as entropy for generating the POP symmetric key. The type of this message attribute must be byte[], PrivateKey, KeyPair, or X509Certificate when the Binary Secret Type is AsymmetricKey. In each case, the private key is used.
Binary Secret Message Attribute:
Enter or select the message attribute that contains the binary secret. This setting is required when the Binary Secret Type is SymmetricKey or AsymmetricKey.
Computed Key Algorithm:
When both the API Gateway and STS provide entropy values for the symmetric POP key, you can specify a computed key algorithm (for example, PSHA1). This is used when the key resulting from the token request is not directly returned, and is computed.
Public Proof of Possession Key:
If the Proof of Possession Key Type requested is a PublicKey, you can specify what public key to include in the token using the following settings:
l Use Key Format: Select how the UseKey element in the RST formats the public key from the list (for example, PublicKey, Certificate, BinarySecurityToken, and so on).
l Use Key Selector Expression: Select or enter the selector expression that contains the public key. The public key can be of type X509Certificate, PublicKey, or KeyPair. Axway API Gateway 7.5.2
Policy Developer Guide 520
12 Authentication filters
Issue: On Behalf Of Token
For Issue requests, you can optionally configure the OnBehalfOf token for the RST. If an OnBehalfOf token is in the RST, this means you are requesting a token on behalf of the subject identified by the token or endpoint reference in the OnBehalfOf element. You can configure the following settings on the Issue: On Behalf Of Token tab:
On Behalf Of:
Select one of the following options:
l None: No OnBehalfOf token is specified. This is the default.
l Token: The token is embedded directly under the <OnBehalfOf> element in the RST.
l EmbeddedSTR: The token is placed in the <OnBehalfOf><SecurityTokenReference><Embedded> element in the RST.
l Endpoint Reference: A reference to the token is placed in the <OnBehalfOf><SecurityTokenReference> element. The token is placed in the WSSecurity header.
On Behalf Of Token Selector Expression:
Enter the selector expression for the message attribute that contains the OnBehalfOf token. This can be a UsernameToken, SAML token, X.509 certificate, and so on. The type of this message attribute can be Node, List of Nodes, String, or X509Certificate. This message attribute must be populated using a filter configured in the policy that applies security before creating the WS-Trust message. For example, this includes a filter to extract a UsernameToken from the incoming message, or a Find Certificate filter.
Endpoint Address:
When the On Behalf Of type is Endpoint Reference, no token is placed in the OnBehalfOf element. Instead, you can enter an endpoint address in this field that identifies the subject on whose behalf you are requesting the token. Identity Type:
When the On Behalf Of type is Endpoint Reference, you can select an identity type from the list (for example, DNSName, ServicePrincipaName, or UserPrincipalName). Identity:
When the Identity Type is set to DNSName, ServicePrincipaName, or UserPrincipalName, you must specify a value in this field. Identity Selector Expression:
When the selected Identity Type is one of PublicKey, Certificate, BinarySecurityToken, SecurityTokenReference_x509v3, or SecurityTokenReference_ThumbprintSHA1, you must specify a selector expression in this field. This specifies the name of the message attribute that contains the certificate for the subject on whose behalf you are requesting the token. The type of this message attribute must be X509Certificate.
Axway API Gateway 7.5.2
Policy Developer Guide 521
12 Authentication filters
Issue: Token Scope and Lifetime
For Issue requests, you can option