Web Reverse Proxy Stanza Reference

IBM Security Web Gateway Appliance

Version 7.0

Web Reverse Proxy Stanza Reference

IBM Security Web Gateway Appliance

Version 7.0

Web Reverse Proxy Stanza Reference

Note

Before using this information and the product it supports, read the information in “Notices” on page 327.

Edition notice

Note: This edition applies to version 7, release 0, modification 0 of IBM Security Access Manager (product number 5724-C87) and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright IBM Corporation 2002, 2013.

Contents

About this publication . . . ix

Intended audience . . . ix

Access to publications and terminology . . . ix

Related publications . . . xii

Accessibility . . . xiv

Technical training . . . xiv

Support information . . . xiv

Stanza reference . . . 1

[acnt-mgt] stanza . . . 1 account-expiry-notification. . . 1 account-inactivated . . . 1 account-locked. . . 2 allow-unauthenticated-logout . . . 3 allowed-referers . . . 3 cert-failure . . . 4 cert-stepup-http . . . 5 certificate-login . . . 5 change-password-auth . . . 6 client-notify-tod . . . 6 enable-html-redirect . . . 7 enable-local-response-redirect . . . 7 enable-passwd-warn . . . 8 enable-secret-token-validation. . . 9 help . . . 10 http-rsp-header . . . 10 html-redirect . . . 11 login. . . 11 login-redirect-page . . . 12 login-success . . . 13 logout . . . 13 passwd-change . . . 14 passwd-change-failure . . . 14 passwd-change-success . . . 15 passwd-expired . . . 15 passwd-warn . . . 16 passwd-warn-failure . . . 16 redirect-to-root-for-pkms . . . 17 single-signoff-uri . . . 17 stepup-login . . . 18 switch-user . . . 19 temp-cache-response . . . 19 too-many-sessions . . . 20 use-restrictive-logout-filenames . . . 20 use-filename-for-pkmslogout . . . 21 [auth-cookies] stanza . . . 21 cookie . . . 21 [authentication-levels] stanza . . . 22 level . . . 22 [aznapi-configuration] stanza . . . 23 audit-attribute . . . 23 auditcfg . . . 23 auditlog . . . 24 cache-refresh-interval . . . 25 cred-attribute-entitlement-services . . . 25 dynamic-adi-entitlement-services . . . 26 input-adi-xml-prolog . . . 26 listen-flags. . . 27 logaudit . . . 27 logclientid . . . 28 logcfg . . . 28 logflush . . . 29 logsize . . . 30 permission-info-returned . . . 30 policy-attr-separator . . . 31 policy-cache-size. . . 31 resource-manager-provided-adi . . . 32 xsl-stylesheet-prolog . . . 33 [azn-decision-info] stanza. . . 33 azn-decision-info . . . . 33 [ba] stanza. . . 34 ba-auth . . . 34 basic-auth-realm . . . 35 [cdsso] stanza . . . 35 authtoken-lifetime . . . 35 cdsso-argument . . . 36 cdsso-auth . . . 36 cdsso-create . . . 37 clean-cdsso-urls . . . 37 propagate-cdmf-errors . . . 38 use-utf8 . . . 38 [cdsso-incoming-attributes] stanza . . . 39 attribute_pattern . . . . 39 [cdsso-peers] stanza . . . 40 fully_qualified_hostname. . . . 40 [cdsso-token-attributes] stanza . . . 40 <default>. . . 40 domain_name . . . . 41 [certificate] stanza . . . 42 accept-client-certs . . . 42 cert-cache-max-entries . . . 42 cert-cache-timeout . . . 43 cert-prompt-max-tries . . . 43 disable-cert-login-page. . . 44 eai-data. . . 45 eai-uri . . . 46 [cert-map-authn] stanza . . . 47 debug-level . . . 47 rules-file . . . 47 [cfg-db-cmd:entries] stanza . . . 48 stanza::entry . . . . 48 [cfg-db-cmd:files] stanza . . . 49 files . . . 49 [cluster] stanza . . . 49 is-master . . . 50 master-name . . . 50 max-wait-time . . . 51 [compress-mime-types] stanza . . . 51 mime_type . . . . 51 [compress-user-agents] stanza . . . 52 pattern . . . . 52

[content] stanza . . . 53 utf8-template-macros-enabled . . . 53 [content-cache] stanza . . . 53 MIME_type . . . 53 [content-encodings] stanza . . . 54 extension . . . 54 [content-index-icons] stanza . . . 55 type . . . . 55 [credential-policy-attributes] stanza . . . 56 policy-name. . . . 56 [credential-refresh-attributes] stanza . . . 57 attribute_name_pattern . . . . 57 authentication_level . . . 57 [dsess] stanza. . . 58 dsess-sess-id-pool-size . . . 58 dsess-cluster-name . . . 58 [dsess-cluster] stanza . . . 59 basic-auth-user . . . 59 basic-auth-passwd . . . 59 gsk-attr-name. . . 60 handle-idle-timeout. . . 61 handle-pool-size . . . 61 response-by . . . 62 server . . . 62 ssl-fips-enabled . . . 63 ssl-keyfile . . . 64 ssl-keyfile-label . . . 64 ssl-keyfile-stash . . . 65 ssl-valid-server-dn . . . 65 timeout . . . 66 [eai] stanza . . . 66 eai-auth . . . 66 eai-auth-level-header . . . 67 eai-flags-header . . . 67 eai-pac-header . . . 68 eai-pac-svc-header . . . 68 eai-redir-url-header . . . 69 eai-session-id-header . . . 69 eai-user-id-header . . . 70 eai-verify-user-identity. . . 70 eai-xattrs-header . . . 71 retain-eai-session . . . 72 [eai-trigger-urls] stanza . . . 72 trigger . . . 72 trigger . . . 73 [e-community-domains] stanza . . . 74 name . . . 74 [e-community-domain-keys] stanza . . . 74 domain_name . . . . 74 [e-community-domain-keys:domain] stanza . . . . 75 domain_name . . . . 75 [e-community-sso] stanza . . . 75 cache-requests-for-ecsso . . . 75 e-community-name . . . 76 disable-ec-cookie . . . 76 e-community-sso-auth . . . 77 ec-cookie-domain . . . 77 ec-cookie-lifetime . . . 78 ecsso-allow-unauth . . . 78 ecsso-propagate-errors . . . 79 handle-auth-failure-at-mas . . . 79 is-master-authn-server . . . 80 master-authn-server . . . 80 master-http-port . . . 81 master-https-port . . . 82 propagate-cdmf-errors . . . 82 use-utf8 . . . 83 vf-argument . . . 83 vf-token-lifetime . . . 84 vf-url . . . 84 [ecsso-incoming-attributes] stanza . . . 85 attribute_pattern . . . . 85 [ecsso-token-attributes] stanza . . . 86 <default> . . . 86 domain_name . . . . 86 [enable-redirects] stanza . . . 87 redirect . . . 87 [failover] stanza . . . 87 clean-ecsso-urls-for-failover . . . 87 enable-failover-cookie-for-domain . . . 88 failover-auth . . . 89 failover-cookie-lifetime . . . 89 failover-cookies-keyfile . . . 90 failover-include-session-id . . . 90 failover-require-activity-timestamp-validation . . 91 failover-require-lifetime-timestamp-validation . . 91 failover-update-cookie . . . 92 reissue-missing-failover-cookie . . . 92 use-utf8 . . . 93 [failover-add-attributes] stanza . . . 93 attribute_pattern . . . . 93 session-activity-timestamp . . . 94 session-lifetime-timestamp . . . 94 [failover-restore-attributes] stanza . . . 95 attribute_pattern . . . . 95 attribute_pattern . . . . 96 [filter-content-types] stanza . . . 96 type . . . 96 [filter-events] stanza . . . 97 HTML_tag . . . . 97 [filter-request-headers] stanza . . . 99 header . . . 99 [filter-schemes] stanza . . . 100 scheme . . . 100 [filter-url] stanza . . . 101 HTML_tag . . . 101 [flow-data] stanza . . . 102 flow-data-enabled . . . 102 flow-data-stats-interval . . . 103 [forms] stanza . . . 103 allow-empty-form-fields . . . 103 forms-auth . . . 104 [gso-cache] stanza . . . 105 gso-cache-enabled . . . 105 gso-cache-entry-idle-timeout . . . 105 gso-cache-entry-lifetime . . . 106 gso-cache-size . . . 106 [header-names] stanza . . . 107 header-data . . . 107 [http-transformations] stanza . . . 108 resource-name . . . 108 [ICAP:<resource>] stanza . . . 109

URL . . . 109 transaction . . . 110 timeout . . . 110 [illegal-url-substrings] stanza . . . 111 substring . . . 111 [interfaces] stanza . . . 111 interface_name . . . 111 [itim] stanza . . . 112 is-enabled . . . 112 itim-server-name . . . 113 itim-servlet-context . . . 113 keydatabase-file . . . 114 keydatabase-password . . . 114 keydatabase-password-file . . . 115 principal-name . . . 116 principal-password . . . 116 service-password-dn . . . 117 service-source-dn . . . 118 service-token-card-dn . . . 119 servlet-port . . . 120 [jdb-cmd:replace] stanza . . . 121 jct-id=search-attr-value|replace-attr-value . . . . 121 [junction] stanza . . . 121 allow-backend-domain-cookies . . . 121 basicauth-dummy-passwd . . . 122 crl-ldap-server . . . 122 crl-ldap-server-port . . . 123 crl-ldap-user. . . 124 crl-ldap-user-password . . . 124 disable-ssl-v2 . . . 125 disable-ssl-v3 . . . 125 disable-tls-v1 . . . 126 disable-tls-v11 . . . 126 disable-tls-v12 . . . 127 dont-reprocess-jct-404s . . . 127 dynamic-addresses . . . 128 http-timeout . . . 129 https-timeout . . . 130 insert-client-real-ip-for-option-r . . . 130 io-buffer-size . . . 131 jct-cert-keyfile . . . 131 jct-cert-keyfile-stash . . . 132 jct-cert-keyfile-pwd . . . 133 jct-ocsp-enable . . . 134 jct-ocsp-max-response-size . . . 134 jct-ocsp-nonce-check-enable. . . 135 jct-ocsp-nonce-generation-enable . . . 135 jct-ocsp-proxy-server-name . . . 136 jct-ocsp-proxy-server-port . . . 136 jct-ocsp-url . . . 137 jct-ssl-reneg-warning-rate . . . 137 jct-undetermined-revocation-cert-action . . . . 138 jmt-map . . . 138 managed-cookies-list . . . 139 mangle-domain-cookies . . . 139 match-vhj-first . . . 140 max-cached-persistent-connections . . . 141 max-webseal-header-size . . . 142 pass-http-only-cookie-atr . . . 142 persistent-con-timeout . . . 143 ping-method . . . 144 ping-time. . . 144 ping-uri . . . 145 recovery-ping-time . . . 145 reprocess-root-jct-404s . . . 146 reset-cookies-list . . . 147 response-code-rules . . . 147 share-cookies . . . 148 support-virtual-host-domain-cookies. . . 149 use-new-stateful-on-error . . . 149 validate-backend-domain-cookies . . . 150 worker-thread-hard-limit . . . 151 worker-thread-soft-limit . . . 151 disable-local-junctions . . . 152 [junction:junction_name] stanza . . . 152 [ldap] stanza . . . 153 auth-timeout . . . 153 auth-using-compare . . . 153 bind-dn . . . 154 bind-pwd. . . 154 cache-enabled . . . 155 cache-group-expire-time . . . 155 cache-group-membership . . . 156 cache-group-size . . . 156 cache-policy-expire-time . . . 157 cache-policy-size . . . 157 cache-return-registry-id . . . 158 cache-user-expire-time . . . 158 cache-user-size . . . 159 cache-use-user-cache . . . 159 default-policy-override-support . . . 160 enabled . . . 160 host . . . 161 login-failures-persistent . . . 162 max-search-size. . . 162 prefer-readwrite-server . . . 163 port . . . 163 replica. . . 164 search-timeout . . . 165 ssl-enabled . . . 165 ssl-keyfile . . . 166 ssl-keyfile-dn . . . 166 ssl-keyfile-pwd . . . 167 ssl-port . . . 167 timeout . . . 168 user-and-group-in-same-suffix . . . 169 [local-response-macros] stanza. . . 169 macro . . . 169 [local-response-redirect] stanza . . . 170 local-response-redirect-uri . . . 170 [logging] stanza . . . 171 absolute-uri-in-request-log . . . 171 agents . . . 171 audit-mime-types . . . 172 audit-response-codes . . . 173 flush-time . . . 173 gmt-time . . . 174 host-header-in-request-log . . . 174 log-invalid-requests . . . 175 max-size . . . 175 referers . . . 176 requests . . . 176

request-log-format . . . 177 server-log-cfg . . . 178 [ltpa] stanza . . . 180 ltpa-auth . . . 180 cookie-name . . . 180 cookie-domain . . . 181 jct-ltpa-cookie-name . . . 181 keyfile. . . 182 update-cookie . . . 182 use-full-dn . . . 183 [ltpa-cache] stanza. . . 184 ltpa-cache-enabled. . . 184 ltpa-cache-entry-idle-timeout . . . 184 ltpa-cache-entry-lifetime . . . 185 ltpa-cache-size . . . 185 [mpa] stanza . . . 186 mpa . . . 186 [oauth-eas] stanza . . . 186 apply-tam-native-policy . . . 186 bad-gateway-rsp-file . . . 187 bad-request-rsp-file . . . 187 cache-size . . . 188 cluster-name. . . 189 default-fed-id . . . 189 default-mode . . . 190 fed-id-param . . . 190 mode-param. . . 191 realm-name . . . 192 trace-component . . . 192 unauthorized-rsp-file . . . 193 [obligations-levels-mapping] stanza . . . 193 obligation . . . . 193 [p3p-header] stanza . . . 194 access . . . 194 categories . . . 195 disputes . . . 197 non-identifiable. . . 197 p3p-element . . . 198 purpose . . . 198 recipient . . . 200 remedies . . . 201 retention . . . 202 [PAM] stanza . . . 202 pam-enabled . . . 202 pam-max-memory . . . 203 pam-use-proxy-header . . . 203 pam-http-parameter . . . 204 pam-coalescer-parameter . . . 204 pam-log-cfg . . . 205 pam-log-audit-events . . . 206 pam-disabled-issues . . . 207 pam-resource-rule . . . 207 [pam-resource:<URI>] stanza . . . . 208 pam-issue . . . . 208 [preserve-cookie-names] stanza . . . 209 name . . . 209 [process-root-filter] stanza . . . 210 root . . . 210 [reauthentication] stanza. . . 210 reauth-at-any-level . . . 210 reauth-extend-lifetime . . . 211 reauth-for-inactive . . . 211 reauth-reset-lifetime . . . 212 terminate-on-reauth-lockout . . . 212 [replica-sets] stanza . . . 213 replica-set . . . 213 [rtss-eas] stanza . . . 213 apply-tam-native-policy . . . 214 audit-log-cfg. . . 214 cluster-name. . . 216 context-id . . . 216 trace-component . . . 217 [rtss-cluster:<cluster>] stanza . . . 217 basic-auth-user . . . 217 basic-auth-passwd . . . 218 handle-idle-timeout . . . 218 handle-pool-size . . . 219 server . . . 219 ssl-fips-enabled . . . 220 ssl-keyfile . . . 221 ssl-keyfile-label . . . 221 ssl-keyfile-stash. . . 222 ssl-valid-server-dn . . . 223 timeout . . . 223 [script-filtering] stanza . . . 224 hostname-junction-cookie . . . 224 rewrite-absolute-with-absolute. . . 224 script-filter . . . 225 [server] stanza . . . 226 allow-shift-jis-chars . . . 226 allow-unauth-ba-supply . . . 226 allow-unsolicited-logins . . . 227 auth-challenge-type . . . 227 cache-host-header . . . 228 capitalize-content-length. . . 229 client-connect-timeout . . . 230 chunk-responses . . . 230 concurrent-session-threads-hard-limit . . . . 231 concurrent-session-threads-soft-limit . . . 231 connection-request-limit . . . 232 cope-with-pipelined-request . . . 232 decode-query . . . 233 disable-timeout-reduction . . . 233 double-byte-encoding. . . 234 dynurl-allow-large-posts. . . 235 dynurl-map . . . 235 enable-IE6-2GB-downloads . . . 236 filter-nonhtml-as-xhtml . . . 236 force-tag-value-prefix . . . 237 http . . . 238 http-method-disabled-local . . . 238 http-method-disabled-remote . . . 239 http-port . . . 239 https . . . 240 https-port . . . 240 ignore-missing-last-chunk . . . 241 intra-connection-timeout. . . 241 io-buffer-size . . . 242 ip-support-level . . . 242 ipv6-support . . . 243 late-lockout-notification . . . 244 max-client-read . . . 244

max-file-cat-command-length . . . 245 max-file-descriptors . . . 245 max-idle-persistent-connections . . . 246 network-interface . . . 247 persistent-con-timeout . . . 247 pre-410-compatible-tokens . . . 248 pre-510-compatible-token . . . 248 preserve-base-href . . . 249 preserve-base-href2 . . . 249 preserve-p3p-policy . . . 250 process-root-requests . . . 250 redirect-using-relative . . . 251 reject-invalid-host-header . . . 252 reject-request-transfer-encodings . . . 252 request-body-max-read . . . 253 request-max-cache . . . 253 send-header-ba-first . . . 254 send-header-spnego-first. . . 255 server-name . . . 255 slash-before-query-on-redirect . . . 256 strip-www-authenticate-headers . . . 257 suppress-backend-server-identity . . . 257 suppress-dynurl-parsing-of-posts . . . 258 suppress-server-identity . . . 258 tag-value-missing-attr-tag . . . 259 use-existing-username-macro-in-custom-redirects 259 use-http-only-cookies . . . 260 utf8-form-support-enabled . . . 261 utf8-qstring-support-enabled . . . 261 utf8-url-support-enabled. . . 262 validate-query-as-ga . . . 262 web-host-name . . . 263 web-http-port . . . 263 web-http-protocol . . . 264 worker-threads . . . 264 [session] stanza. . . 265 dsess-enabled . . . 265 dsess-last-access-update-interval . . . 265 enforce-max-sessions-policy . . . 266 inactive-timeout . . . 266 logout-remove-cookie. . . 267 max-entries . . . 268 prompt-for-displacement . . . 268 register-authentication-failures . . . 269 require-mpa . . . 269 resend-webseal-cookies . . . 270 send-constant-sess . . . 270 shared-domain-cookie . . . 271 ssl-id-sessions . . . 272 ssl-session-cookie-name . . . 272 standard-junction-replica-set . . . 273 tcp-session-cookie-name . . . 273 temp-session-cookie-name . . . 274 temp-session-max-lifetime . . . 274 timeout . . . 275 update-session-cookie-in-login-request . . . . 275 user-session-ids. . . 276 user-session-ids-include-replica-set . . . 277 use-same-session . . . 277 [session-cookie-domains] stanza . . . 278 domain . . . 278 [session-http-headers] stanza . . . 278 header_name . . . . 278 [ssl] stanza . . . 279 base-crypto-library . . . 279 crl-ldap-server . . . 279 crl-ldap-server-port . . . 280 crl-ldap-user. . . 281 crl-ldap-user-password . . . 281 disable-ssl-v2 . . . 282 disable-ssl-v3 . . . 282 disable-tls-v1 . . . 283 disable-tls-v11 . . . 283 disable-tls-v12 . . . 284 enable-duplicate-ssl-dn-not-found-msgs . . . 284 fips-mode-processing . . . 285 gsk-attr-name . . . 285 gsk-crl-cache-entry-lifetime . . . 287 gsk-crl-cache-size . . . 287 jct-gsk-attr-name . . . 288 ocsp-enable . . . 289 ocsp-max-response-size . . . 290 ocsp-nonce-check-enable. . . 290 ocsp-nonce-generation-enable . . . 291 ocsp-proxy-server-name . . . 291 ocsp-proxy-server-port . . . 292 ocsp-url . . . 292 ssl-keyfile . . . 293 ssl-keyfile-label . . . 293 ssl-keyfile-pwd . . . 294 ssl-keyfile-stash. . . 294 ssl-local-domain . . . 295 ssl-max-entries . . . 295 ssl-v2-timeout . . . 296 ssl-v3-timeout . . . 297 suppress-client-ssl-errors . . . 297 undetermined-revocation-cert-action . . . 298 webseal-cert-keyfile . . . 298 webseal-cert-keyfile-label . . . 299 webseal-cert-keyfile-pwd . . . 299 webseal-cert-keyfile-sni . . . 300 webseal-cert-keyfile-stash . . . 301 [ssl-qop] stanza. . . 301 ssl-qop-mgmt . . . 301 [ssl-qop-mgmt-default] stanza . . . 302 default . . . 302 [ssl-qop-mgmt-hosts] stanza . . . 303 host-ip . . . . 303 [ssl-qop-mgmt-networks] stanza . . . 304 network/netmask . . . . 304 [step-up] stanza . . . 305 retain-stepup-session . . . 305 show-all-auth-prompts . . . 305 step-up-at-higher-level . . . 306 verify-step-up-user . . . 306 [system-environment-variables] stanza . . . 307 env-name . . . . 307 [tfimsso:<jct-id>] stanza . . . 308 always-send-tokens . . . 308 applies-to. . . 308 one-time-token . . . 309 preserve-xml-token . . . 309

renewal-window . . . 310 service-name . . . 310 tfim-cluster-name . . . 311 token-collection-size . . . 311 token-type . . . 312 token-transmit-name . . . 313 token-transmit-type . . . 313 [tfim-cluster:<cluster>] stanza . . . . 314 basic-auth-user . . . 314 basic-auth-passwd . . . 314 gsk-attr-name . . . 315 handle-idle-timeout . . . 316 handle-pool-size . . . 316 server . . . 317 ssl-fips-enabled . . . 317 ssl-keyfile . . . 318 ssl-keyfile-label . . . 319 ssl-keyfile-stash. . . 319 ssl-valid-server-dn . . . 320 timeout . . . 321 [uraf-registry] stanza . . . 321 bind-id . . . 321 cache-lifetime . . . 322 cache-mode . . . 322 cache-size . . . 323 [user-agent] stanza . . . 324 user-agent . . . . 324

Notices . . . 327

Index . . . 331

About this publication

Welcome to the IBM Security Web Gateway Appliance: Web Reverse Proxy Stanza

Reference.

IBM Security Access Manager for Web, formerly called IBM Tivoli Access Manager for e-business, is a user authentication, authorization, and web single sign-on solution for enforcing security policies over a wide range of web and application resources.

The IBM Security Web Gateway Appliance includes Security Access Manager. The appliance uses a Web Reverse Proxy to provide user access and authentication management for web application sessions. This guide uses the term WebSEAL to reference this proxy.

Security Access Manager WebSEAL is the resource manager for web-based resources in a Security Access Manager secure domain. WebSEAL is a high

performance, multi-threaded web server that applies fine-grained security policy to the protected web object space. WebSEAL can provide single signon solutions and incorporate back-end web application server resources into its security policy.

This guide provides the complete stanza reference for configuring WebSEAL. You can use this guide in conjunction with the IBM Security Web Gateway Appliance:

Configuration Guide for Web Reverse Proxy, which provides valuable background and

concept information for the wide range of WebSEAL functionality.

Intended audience

This guide is for system administrators responsible for configuring and maintaining a Security Access Manager WebSEAL environment.

Readers should be familiar with the following: v _{PC and UNIX or Linux operating systems} v _{Database architecture and concepts} v _{Security management}

v _{Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and} Telnet

v _{Lightweight Directory Access Protocol (LDAP) and directory services} v _{A supported user registry}

v _WebSphere®_{Application Server administration} v _{Authentication and authorization}

If you are enabling Secure Sockets Layer (SSL) communication, you also should be familiar with SSL protocol, key exchange (public and private), digital signatures, cryptographic algorithms, and certificate authorities.

Access to publications and terminology

v _{A list of publications in the “IBM Security Access Manager for Web library.”} v _{Links to “Online publications” on page xii.}

v _{A link to the “IBM Terminology website” on page xii.}

IBM Security Access Manager for Web library

The following documents are in the IBM Security Access Manager for Web library: v _{IBM Security Access Manager for Web Quick Start Guide, GI11-9333-01}

Provides steps that summarize major installation and configuration tasks. v _{IBM Security Web Gateway Appliance Quick Start Guide – Hardware Offering}

Guides users through the process of connecting and completing the initial configuration of the WebSEAL Hardware Appliance, SC22-5434-00

v _{IBM Security Web Gateway Appliance Quick Start Guide – Virtual Offering} Guides users through the process of connecting and completing the initial configuration of the WebSEAL Virtual Appliance.

v _{IBM Security Access Manager for Web Installation Guide, GC23-6502-02} Explains how to install and configure Security Access Manager. v _{IBM Security Access Manager for Web Upgrade Guide, SC23-6503-02}

Provides information for users to upgrade from version 6.0, or 6.1.x to version 7.0.

v _{IBM Security Access Manager for Web Administration Guide, SC23-6504-02} Describes the concepts and procedures for using Security Access Manager. Provides instructions for performing tasks from the Web Portal Manager interface and by using the pdadmin utility.

v _{IBM Security Access Manager for Web WebSEAL Administration Guide, SC23-6505-02} Provides background material, administrative procedures, and reference

information for using WebSEAL to manage the resources of your secure Web domain.

v _{IBM Security Access Manager for Web Plug-in for Web Servers Administration Guide,} SC23-6507-02

Provides procedures and reference information for securing your Web domain by using a Web server plug-in.

v _{IBM Security Access Manager for Web Shared Session Management Administration}

Guide, SC23-6509-02

Provides administrative considerations and operational instructions for the session management server.

v _{IBM Security Access Manager for Web Shared Session Management Deployment Guide,} SC22-5431-00

Provides deployment considerations for the session management server. v _{IBM Security Web Gateway Appliance Administration Guide, SC22-5432-00}

Provides administrative procedures and technical reference information for the WebSEAL Appliance.

v _{IBM Security Web Gateway Appliance Configuration Guide for Web Reverse Proxy,} SC22-5433-00

Provides configuration procedures and technical reference information for the WebSEAL Appliance.

v _{IBM Security Web Gateway Appliance Web Reverse Proxy Stanza Reference,} SC27-4442-00

Provides a complete stanza reference for the IBM®Security Web Gateway Appliance Web Reverse Proxy.

v _{IBM Security Access Manager for Web WebSEAL Configuration Stanza Reference,} SC27-4443-00

Provides a complete stanza reference for the WebSEAL Appliance. v _{IBM Global Security Kit: CapiCmd Users Guide, SC22-5459-00}

Provides instructions on creating key databases, public-private key pairs, and certificate requests.

v _{IBM Security Access Manager for Web Auditing Guide, SC23-6511-02}

Provides information about configuring and managing audit events by using the native Security Access Manager approach and the Common Auditing and Reporting Service. You can also find information about installing and

configuring the Common Auditing and Reporting Service. Use this service for generating and viewing operational reports.

v _{IBM Security Access Manager for Web Command Reference, SC23-6512-02}

Provides reference information about the commands, utilities, and scripts that are provided with Security Access Manager.

v _{IBM Security Access Manager for Web Administration C API Developer Reference,} SC23-6513-02

Provides reference information about using the C language implementation of the administration API to enable an application to perform Security Access Manager administration tasks.

v _{IBM Security Access Manager for Web Administration Java Classes Developer}

Reference, SC23-6514-02

Provides reference information about using the Java™language implementation of the administration API to enable an application to perform Security Access Manager administration tasks.

v _{IBM Security Access Manager for Web Authorization C API Developer Reference,} SC23-6515-02

Provides reference information about using the C language implementation of the authorization API to enable an application to use Security Access Manager security.

v _{IBM Security Access Manager for Web Authorization Java Classes Developer Reference,} SC23-6516-02

Provides reference information about using the Java language implementation of the authorization API to enable an application to use Security Access Manager security.

v _{IBM Security Access Manager for Web Web Security Developer Reference,} SC23-6517-02

Provides programming and reference information for developing authentication modules.

v _{IBM Security Access Manager for Web Error Message Reference, GI11-8157-02} Provides explanations and corrective actions for the messages and return code. v _{IBM Security Access Manager for Web Troubleshooting Guide, GC27-2717-01}

Provides problem determination information.

v _{IBM Security Access Manager for Web Performance Tuning Guide, SC23-6518-02} Provides performance tuning information for an environment that consists of Security Access Manager with the IBM Tivoli Directory Server as the user registry.

Online publications

IBM posts product publications when the product is released and when the publications are updated at the following locations:

IBM Security Access Manager for Web Information Center

The http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/

com.ibm.isam.doc_70/welcome.html site displays the information center welcome page for this product.

IBM Publications Center

The http://www-05.ibm.com/e-business/linkweb/publications/servlet/ pbi.wss site offers customized search functions to help you find all the IBM publications that you need.

IBM Terminology website

The IBM Terminology website consolidates terminology for product libraries in one location. You can access the Terminology website at http://www.ibm.com/

software/globalization/terminology.

Related publications

This section lists the IBM products that are related to and included with the Security Access Manager solution.

Note: The following middleware products are not packaged with IBM Security Web Gateway Appliance.

IBM Global Security Kit

Security Access Manager provides data encryption by using Global Security Kit (GSKit) version 8.0.x. GSKit is included on the IBM Security Access Manager for Web

Version 7.0 product image or DVD for your particular platform.

GSKit version 8 includes the command-line tool for key management, GSKCapiCmd (gsk8capicmd_64).

GSKit version 8 no longer includes the key management utility, iKeyman

(gskikm.jar). iKeyman is packaged with IBM Java version 6 or later and is now a pure Java application with no dependency on the native GSKit runtime. Do not move or remove the bundled java/jre/lib/gskikm.jar library.

The IBM Developer Kit and Runtime Environment, Java Technology Edition, Version 6

and 7, iKeyman User's Guide for version 8.0 is available on the Security Access

Manager Information Center. You can also find this document directly at:

http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/security/ 60/iKeyman.8.User.Guide.pdf

Note:

GSKit version 8 includes important changes made to the implementation of Transport Layer Security required to remediate security issues.

The GSKit version 8 changes comply with the Internet Engineering Task Force (IETF) Request for Comments (RFC) requirements. However, it is not compatible

with earlier versions of GSKit. Any component that communicates with Security Access Manager that uses GSKit must be upgraded to use GSKit version 7.0.4.42, or 8.0.14.26 or later. Otherwise, communication problems might occur.

IBM Tivoli Directory Server

IBM Tivoli Directory Server version 6.3 FP17 (6.3.0.17-ISS-ITDS-FP0017) is included on the IBM Security Access Manager for Web Version 7.0 product image or DVD for your particular platform.

You can find more information about Tivoli Directory Server at:

http://www.ibm.com/software/tivoli/products/directory-server/

IBM Tivoli Directory Integrator

IBM Tivoli Directory Integrator version 7.1.1 is included on the IBM Tivoli Directory

Integrator Identity Edition V 7.1.1 for Multiplatform product image or DVD for your

particular platform.

You can find more information about IBM Tivoli Directory Integrator at:

http://www.ibm.com/software/tivoli/products/directory-integrator/

IBM DB2 Universal Database

™

IBM DB2 Universal Database Enterprise Server Edition, version 9.7 FP4 is provided on the IBM Security Access Manager for Web Version 7.0 product image or DVD for your particular platform. You can install DB2®with the Tivoli Directory Server software, or as a stand-alone product. DB2 is required when you use Tivoli Directory Server or z/OS®LDAP servers as the user registry for Security Access Manager. For z/OS LDAP servers, you must separately purchase DB2.

You can find more information about DB2 at:

http://www.ibm.com/software/data/db2

IBM WebSphere products

The installation packages for WebSphere Application Server Network Deployment, version 8.0, and WebSphere eXtreme Scale, version 8.5.0.1, are included with Security Access Manager version 7.0. WebSphere eXtreme Scale is required only when you use the Session Management Server (SMS) component.

WebSphere Application Server enables the support of the following applications: v _{Web Portal Manager interface, which administers Security Access Manager.} v _{Web Administration Tool, which administers Tivoli Directory Server.}

v _{Common Auditing and Reporting Service, which processes and reports on audit} events.

v _{Session Management Server, which manages shared session in a Web security} server environment.

v _{Attribute Retrieval Service.}

http://www.ibm.com/software/webservers/appserv/was/library/

Accessibility

Accessibility features help users with a physical disability, such as restricted mobility or limited vision, to use software products successfully. With this product, you can use assistive technologies to hear and navigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface.

Visit the IBM Accessibility Center for more information about IBM's commitment to accessibility.

Technical training

For technical training information, see the following IBM Education website at http://www.ibm.com/software/tivoli/education.

Support information

IBM Support provides assistance with code-related problems and routine, short duration installation or usage questions. You can directly access the IBM Software Support site at http://www.ibm.com/software/support/probsub.html.

The IBM Security Access Manager for Web Troubleshooting Guide provides details about:

v _{What information to collect before you contact IBM Support.} v _{The various methods for contacting IBM Support.}

v _{How to use IBM Support Assistant.}

v _{Instructions and problem-determination resources to isolate and fix the problem} yourself.

Note: The Community and Support tab on the product information center can provide more support resources.

Stanza reference

This guide provides a complete stanza reference for the WebSEAL configuration file, alphabetized by stanza name.

You can use the IBM Security Web Gateway Appliance Local Management Interface (LMI) to edit the WebSEAL configuration file. On the Reverse Proxy management page, select the appropriate WebSEAL instance and click Manage >

Configuration > Edit Configuration File to open the Advanced Configuration File Editor. You can use this editor to directly edit the WebSEAL configuration file.

For more details about the WebSEAL configuration file naming and structure, see the IBM Security Web Gateway Appliance: Configuration Guide for Web Reverse Proxy. For more information about administering the appliance and navigating the LMI, see the IBM Security Web Gateway Appliance: Administration Guide.

[acnt-mgt] stanza

account-expiry-notification

Syntax

account-expiry-notification = {yes|no}

Description

Specifies whether WebSEAL informs the user of the reason for a login failure when the failure is due to an invalid or expired account. When this entry is set to no, the user receives the same error message as that which is sent when a login fails due to invalid authentication information, such as an invalid user name or password.

Options

yes Enable.

no Disable.

Usage

This stanza entry is required.

Default value

no

Example

account-expiry-notification = yes

account-inactivated

Syntax

account-inactivated = filename

Description

Page displayed when nsAccountLock is true for a user (in Sun Directory Server) when they attempt to login. This page will only be displayed if they provide the correct password during login.

NOTE:This option has no effect unless the corresponding Security Access Manager LDAP option is enabled ([ldap] enhanced-pwd-policy=yes). This LDAP option must be supported for the particular LDAP registry type.

Options

filename

Page displayed when nsAccountLock is true for the user who has provided the correct password during login.

Usage

This stanza entry is required.

Default value

None.

NOTE:The value for this option in the template configuration file is acct_locked.html.

Example

account-inactivated = acct_locked.html

account-locked

Syntax

account-locked = filename

Description

Page displayed when the user authentication fails due to a locked user account.

Options

filename

Page displayed when the user authentication fails due to a locked user account.

Usage

This stanza entry is required.

Default value

acct_locked.html

Example

allow-unauthenticated-logout

Syntax

allow-unauthenticated-logout = {yes|no}

Description

Determines whether unauthenticated users are able to request the pkmslogout resource without authenticating first.

Options

yes Allow unauthenticated users to be able to request the pkmslogout resource.

no Unauthenticated users must authenticate before the pkmslogout resource is returned.

Usage

This stanza entry is required.

Default value

no

Example

allow-unauthenticated-logout = no

allowed-referers

Syntax

allowed-referers = referer_filter

Description

For protection against cross-site request forgery (CSRF) attacks, you can configure WebSEAL to validate the HTTP Request referer header for all account

management pages. WebSEAL uses the value provided for this configuration entry to determine whether the referrer host name in an incoming request is "valid".

If this entry is configured, when WebSEAL receives a request for an account management page, WebSEAL:

1. Checks whether the referer header is present in the HTTP Request header. 2. Validates the host name portion of that referrer against the allowed-referers

entries.

If WebSEAL finds that an incoming request does not match any of the configured

allowed-referersfilters, the request fails and WebSEAL returns an error page. Entries can contain the following wildcard characters:

v _{*- match 0 or more characters.} v _{?- match any single character.}

You can use the value %HOST% for this entry. This value is a special filter, which indicates to WebSEAL that a referrer is "valid" if the host name portion of the

referer header matches the host header.

If there are no allowed-referers entries then WebSEAL does not complete this validation.

Note: You can specify this entry multiple times to define multiple "allowed" referrer filters. WebSEAL uses all of these entries when validating the referrer.

For more information about referrer validation, search for "CSRF" in the IBM

Security Web Gateway Appliance: Configuration Guide for Web Reverse Proxy.

Options

referer_filter

Specifies a filter for a referrer host name that WebSEAL can accept as "valid".

Usage

This stanza entry is optional.

Default value

None.

Example

The following entry matches any referrer host name that begins with the characters ac, followed by zero or more characters, and ends with the characters me.

allowed-referers = ac*me

The following entry indicates that a referrer is "valid" if the host name portion of the referer header matches the host header.

allowed-referers = %HOST%

cert-failure

Syntax

cert-failure = filename

Description

Page displayed when certificates are required and a client fails to authenticate with a certificate.

Options

filename

Page displayed when certificates are required and a client fails to authenticate with a certificate.

Usage

Default value

certfailure.html

Example

cert-failure = certfailure.html

cert-stepup-http

Syntax

cert-stepup-http = filename

Description

WebSEAL displays this HTML page when a client attempts to increase

authentication strength level (step-up) to certificates while using HTTP protocol.

Options

filename

WebSEAL displays this HTML page when a client attempts to increase authentication strength level (step-up) to certificates while using HTTP protocol.

Usage

This stanza entry is required.

Default value

certstepuphttp.html

Example

cert-stepup-http = certstepuphttp.html

certificate-login

Syntax

certificate-login = filename

Description

Form requesting client-side certificate authentication login.

This form is used only when the accept-client-certs key in the [certificate] stanza is set to prompt_as_needed.

Options

filename

Form requesting client-side certificate authentication login.

Usage

This stanza entry is required when delayed certificate authentication or authentication strength level (step-up) for certificates is enabled.

Default value

certlogin.html

Example

certificate-login = certlogin.html

change-password-auth

Syntax

change-password-auth = {yes|no}

Description

Enable this option to allow users to authenticate when changing a password.

Options

yes Enable.

no Disable.

Usage

This stanza entry is required.

Default value

no

Example

change-password-auth = yes

client-notify-tod

Syntax

client-notify-tod = {yes|no}

Description

Enable the display of an error page when authorization is denied due to a POP time of day check. The error page is 38cf08cc.html.

Options

yes Enable.

no Disable.

Usage

This stanza entry is required.

Default value

no

Example

client-notify-tod = yes

enable-html-redirect

Syntax

enable-html-redirect = {yes|no}

Description

Configures WebSEAL to use the HTML redirect page to handle redirections rather than returning an HTTP 302 response redirect.

When a user successfully authenticates, WebSEAL typically uses an HTTP 302 response to redirect the user back to the resource that was originally requested.

HTML redirection causes WebSEAL to send a static page back to the browser instead of a 302 redirect. WebSEAL can then use the JavaScript or any other code that is embedded in this static page to process the redirect.

You can use the html-redirect configuration entry, which is also in the [acnt-mgt] stanza, to specify the page that contains the HTML redirection.

For more information about HTML redirection, see the IBM Security Web Gateway

Appliance: Configuration Guide for Web Reverse Proxy.

Note: If you enable this configuration entry, you must not specify a value for the

login-redirect-pageentry, which is also in the [acnt-mgt] stanza.

Options

yes Enable.

no Disable.

Usage

This stanza entry is required.

Default value

no

Example

enable-html-redirect = no

enable-local-response-redirect

Syntax

enable-local-response-redirect = {yes|no}

Description

Enable or disable sending a redirection to a response application instead of serving management or error pages from the local system.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [acnt-mgt:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

yes Enable.

no Disable.

Usage

This stanza entry is required.

Default value

no

Example

enable-local-response-redirect = no

enable-passwd-warn

Syntax

enable-passwd-warn = {yes|no}

Description

Enable WebSEAL to detect the attribute REGISTRY_PASSWORD_EXPIRE_TIME added to a users' credential when the LDAP password policy indicates that their password is soon to expire. The value of this attribute is the number of seconds until their password expires. When this attribute is detected, at login to WebSEAL, a password warning form will appear.

NOTE:This option must be set in order to use the associated options, which are also in the [acnt-mgt] stanza: passwd-warn and passwd-warn-failure. The corresponding Security Access Manager LDAP option must be enabled ([ldap] enhanced-pwd-policy=yes) and supported for the particular LDAP registry type.

Options

yes Enable the detection of the REGISTRY_PASSWORD_EXPIRE_TIME to ultimately warn the user when their password is soon to expire.

no Disable the detection of the REGISTRY_PASSWORD_EXPIRE_TIME attribute. WebSEAL will not be able to notify users when their passwords are soon to expire.

Usage

Default value

The option will default to yes if it is not specified in the configuration file.

NOTE:The value for this option in the template configuration file is no.

Example

enable-passwd-warn = yes

enable-secret-token-validation

Syntax

enable-secret-token-validation = {true|false}

Description

Use this entry to enable secret token validation, which protects certain WebSEAL account management pages against cross-site request forgery (CSRF) attacks. If you set this entry to true, WebSEAL adds a token to each session and validates the "token" query argument for the following account management requests: v _{/pkmslogin.form} v _/pkmslogout v _{/pkmslogout-nomas} v _/pkmssu.form v _/pkmsskip v _{/pkmsdisplace} v _{/pkmspaswd.form}

For example, you must change the /pkmslogout request to

pkmslogout?token=<value>, where <value> is the unique session token.

If secret token validation is enabled and the token argument is missing from the request or does not match the session token, WebSEAL returns an error page. For more information about secret token validation, search for "CSRF" in the IBM

Security Web Gateway Appliance: Configuration Guide for Web Reverse Proxy.

Options

true WebSEAL uses secret token validation to protect against CSRF attacks.

Note: This setting modifies the URLs for the affected WebSEAL

management pages. Each of these management requests must contain a "token" argument with the current session token.

false WebSEAL does not use secret token validation.

Usage

This stanza entry is optional.

Default value

false

Example

help

Syntax

help = filename

Description

Page containing links to valid administration pages.

Options

filename

Page containing links to valid administration pages.

Usage

This stanza entry is required.

Default value

help.html

Example

help = help.html

http-rsp-header

Syntax

http-rsp-header = header-name:macro

Description

Inserts custom headers whenever WebSEAL returns a custom response to the client.

Options

header-name

The name of the header that holds the value.

macro That type of value to be inserted. This parameter can be one of the following values:

v _{TAM_OP}

v _AUTHNLEVEL

v _{ERROR_CODE} v _{ERROR_TEXT}

v _{CREDATTR(<name>), where <name> is the name of the credential} attribute.

v _USERNAME

Usage

Note: You can specify this entry multiple times to include multiple headers in the response.

Default value

None.

Example

The following example inserts the Security Access Manager error code in a response header named tam-error-code:

http-rsp-header = tam-error-code:ERROR_CODE

html-redirect

Syntax

html-redirect = filename

Description

Specifies the standard HTML redirection page.

Options

filename

Standard HTML redirection page.

Usage

This stanza entry is required.

Default value

redirect.html.

Example

html-redirect = redirect.html

login

Syntax

login = filename

Description

Standard login form.

Options

filename

Standard login form.

Usage

Default value

login.html

Example

login = login.html

login-redirect-page

Syntax

login-redirect-page = destination

Description

Page to which users are automatically redirected after completing a successful authentication. The configured redirect destination can be either:

v _{A server-relative Uniform Resource Locator (URL), or} v _{An absolute URL, or}

v _{A macro which allows dynamic substitution of information from WebSEAL.}

The supported macros include:

%AUTHNLEVEL%

Level at which the session is currently authenticated.

%HOSTNAME%

Fully qualified host name.

%PROTOCOL%

The client connection protocol used. Can be HTTP or HTTPS.

%URL%

The original URL requested by the client.

%USERNAME%

The name of the logged in user.

%HTTPHDR{name}%

The HTTP header that corresponds to the specified name. For example: %HTTPHDR{Host}%

%CREDATTR{name}%

The credential attribute with the specified name. For example: %CREDATTR{tagvalue_session_index}%

Note: You cannot use this configuration entry if the enable-js-redirect entry (also in the [acnt-mgt] stanza) is set to yes. These redirects are not compatible with one another.

Options

destination

Uniform Resource Locator (URL) to which users are automatically redirected after login, or a macro for dynamic substitution of information from WebSEAL.

Usage

Default value

None.

Example

Example of a server relative URL: login-redirect-page = /jct/page.html Example of an absolute URL:

login-redirect-page = http://www.ibm.com/ Example that uses a macro:

login-redirect-page = /jct/intro-page.html?level=%AUTHNLEVEL%&url=%URL%

login-success

Syntax

login-success = filename

Description

Page displayed after successful login.

Options

filename

Page displayed after successful login.

Usage

This stanza entry is required.

Default value

login_success.html

Example

login-success = login_success.html

logout

Syntax

logout = filename

Description

Page displayed after successful logout.

Options

filename

Usage

This stanza entry is required.

Default value

logout.html

Example

logout = logout.html

passwd-change

Syntax

passwd-change = filename

Description

Page containing a change password form.

Options

filename

Page containing a change password form.

Usage

This stanza entry is required.

Default value

passwd.html

Example

passwd-change = passwd.html

passwd-change-failure

Syntax

passwd-change-failure = filename

Description

Page displayed when password change request fails.

Options

filename

Page displayed when password change request fails.

Usage

Default value

passwd.html

Example

passwd-change-failure = passwd.html

passwd-change-success

Syntax

passwd-change-success = filename

Description

Page displayed when password change request succeeds.

Options

filename

Page displayed when password change request succeeds.

Usage

This stanza entry is required.

Default value

passwd_rep.html

Example

passwd-change-success = passwd_rep.html

passwd-expired

Syntax

passwd-expired = filename

Description

Page displayed when the user authentication fails due to an expired user password.

Options

filename

Page displayed when the user authentication fails due to an expired user password.

Usage

This stanza entry is required.

Default value

passwd_exp.html

Example

passwd-expired = passwd_exp.html

passwd-warn

Syntax

passwd-warn = filename

Description

Page displayed after login if WebSEAL detects the LDAP password is soon to expire.

NOTE:This option has no effect unless enable-passwd-warn (also in the

[acnt-mgt]stanza) is set to yes and the corresponding Security Access Manager LDAP option is also enabled ([ldap] enhanced-pwd-policy=yes). This LDAP option must be supported for the particular LDAP registry type.

Options

filename

Page displayed as a warning that the LDAP password is soon to expire.

Usage

This stanza entry is required.

Default value

None.

NOTE:The value for this option in the template configuration file is passwd_warn.html.

Example

passwd-warn = passwd_warn.html

passwd-warn-failure

Syntax

passwd-warn-failure = filename

Description

Page displayed if the user fails to change their password after being notified that the LDAP password is soon to expire. This page gives the user another chance to change their password and indicates the cause of the error.

NOTE:This option has no effect unless enable-passwd-warn (also in the

[acnt-mgt]stanza) is set to yes and the corresponding Security Access Manager LDAP option is also enabled ([ldap] enhanced-pwd-policy=yes). This LDAP option must be supported for the particular LDAP registry type.

Options

filename

Page displayed if the user does not change their password after receiving notification that the LDAP password is soon to expire.

Usage

This stanza entry is required.

Default value

None.

NOTE:The value for this option in the template configuration file is passwd_warn.html.

Example

passwd-warn-failure = passwd_warn.html

redirect-to-root-for-pkms

Syntax

redirect-to-root-for-pkms = {yes|no}

Description

In older releases, WebSEAL would, in rare cases, redirect clients to the document root directory instead of returning the login success page following a successful authentication. This behavior was eliminated in later releases. Set

redirect-to-root-for-pkmsto yes to restore the previous behavior.

Options

yes Restore previous behavior.

no Maintain default behavior.

Usage

This stanza entry is required.

Default value

no

Example

redirect-to-root-for-pkms = no

single-signoff-uri

Syntax

single-signoff-uri = URI

Description

When a user session is terminated in WebSEAL, any sessions that might exist on backend application servers are not destroyed. You can use this configuration entry to change this default behavior.

When a WebSEAL user session is terminated and this stanza entry is configured, WebSEAL sends a request to the resource specified by the configured URI. The request contains any configured headers and cookies for the junction point on which the resource resides. The backend application can use this information to terminate any sessions for that user.

Note: You can configure more than one single-sign-off-uri entry to send a request to multiple URIs.

Options

URI

The resource identifier of the application that receives the single signoff request from WebSEAL.

Note: The URI must be server relative and correspond to a resource on a standard junction.

Usage

This stanza entry is optional.

Default value

None.

Example

single-signoff-uri = /management/logoff

stepup-login

Syntax

stepup-login = filename

Description

Step-up authentication login form.

Options

filename

Step-up authentication login form.

Usage

This stanza entry is required.

Default value

stepuplogin.html

Example

stepup-login = stepuplogin.html

switch-user

Syntax

switch-user = filename

Description

Switch user management form.

Options

filename

Switch user management form.

Usage

This stanza entry is required.

Default value

switchuser.html

Example

switch-user = switchuser.html

temp-cache-response

Syntax

temp-cache-response = filename

Description

The default page that WebSEAL returns if no URL redirect is supplied with the pkmstempsession request. The pkmstempsession page is accessed to achieve session sharing with Microsoft Office applications. For more information about sharing sessions with Microsoft Office applications, see the IBM Security Web Gateway

Appliance: Configuration Guide for Web Reverse Proxy.

Options

filename

The default page that WebSEAL returns for a pkmstempsession request.

Usage

This stanza entry is optional.

Default value

Example

temp-cache-response = temp_cache_response.html

too-many-sessions

Syntax

too-many-sessions = filename

Description

Page displayed when a user has too many concurrent sessions and must either cancel their new login or terminate the other sessions.

Options

filename

Page displayed when a user has too many concurrent sessions and must either cancel their new login or terminate the other sessions.

Usage

This stanza entry is required.

Default value

too_many_sessions.html

Example

too-many-sessions = too_many_sessions.html

use-restrictive-logout-filenames

Syntax

use-restrictive-logout-filenames = {yes|no}

Description

Control the restrictions normally enforced on the name of the /pkmslogout custom response file.

Options

yes Use default restrictions to enforce the name of the /pkmslogout custom response file.

no Only slash (/), backslash (\), characters outside of the ASCII range 0x20 -0x7E, and filenames that begin with a period (.) will be disallowed.

Usage

This stanza entry is required.

Default value

yes

Example

use-restrictive-logout-filenames = yes

use-filename-for-pkmslogout

Syntax

use-filename-for-pkmslogout = {yes|no}

Description

Controls whether or not the appended query string (specifying a custom response page) in a pkmslogout command is used to override the default response page.

Options

yes Enables the operation of the query string. If a query string in a

pkmslogout URL specifies a custom response page, that custom page is used instead of the default page.

no Disables the operation of the query string. Any query string in a

pkmslogout URL that specifies a custom response page is ignored. Only the default response page is used upon logout.

Usage

This stanza entry is required.

Default value

no

Example

use-filename-for-pkmslogout = yes

[auth-cookies] stanza

cookie

Syntax

cookie = cookie-name

Description

Specifies HTTP cookies to be used for authentication.

Note: This option is enabled only when the http-headers-auth option in the

[http-headers] stanza is configured for http, https, or both.

Options

cookie-name

Usage

This stanza entry is optional.

Default value

None.

Example

cookie = authcookie

[authentication-levels] stanza

level

Syntax

level = method-name

Description

Step-up authentication levels. WebSEAL enables authenticated users to increase the authentication level by use of step-up authentication. This key=value pair specifies which step-up authentication levels are supported by this WebSEAL server.

Do not specify an authentication level unless the authentication method is enabled. For example, you must enable either basic authentication or forms authentication before you set level = password.

Enter a separate key=value pair for each supported level. Supported levels include: v _{unauthenticated}

v _password v _ssl

v _{ext-auth-interface}

The position of the entry in the file dictates the associated authentication level. The first row, typically unauthenticated, is associated with authentication level of 0. Each subsequent line is associated with the next higher level. You can add multiple entries for the same method.

It is possible for the method to set the authentication level itself. For example, an External Authentication Interface (EAI) implementation might set either

authentication level of 2 or 3 depending on the authentication transaction that the client undertakes.

The EAI can set this authentication level directly in the identity attributes returned to WebSEAL. To support this implementation, you can create two identical lines in positions 3 and 4. For example:

level = unauthenticated (associated with level 0)

level = password (associated with level 1)

level = ext-auth-interface (associated with level 2) level = ext-auth-interface (associated with level 3)

Options

method-name

Name of authentication method.

Usage

This stanza entry is required.

Default value

unauthenticated password

Example

level = unauthenticated level = password

[aznapi-configuration] stanza

audit-attribute

Syntax

audit-attribute = attribute

Description

Attributes to be audited.

Options

attribute Attributes to be audited.

Usage

This stanza entry is required.

Default value

tagvalue_su-admin

Example

audit-attribute = tagvalue_su-admin

auditcfg

Syntax

auditcfg = {azn|authn|http}

Description

Indicates the components for which auditing of events is configured. To enable component specific audit records, add the appropriate definition.

Options

azn Capture authorization events.

authn Capture authentication events.

http Capture HTTP events. These correspond to the events logged by the request, referer, and agent logging clients.

Usage

This stanza entry is optional for WebSEAL. However, this stanza entry is required when auditing is enabled (logaudit = yes).

Default value

There is no default value for WebSEAL, because auditing is disabled by default.

Example

Create a separate stanza entry for each component to be activated. The components are included in the default configuration file but are commented out. To activate a commented out entry, remove the pound sign (#) from the start of the entry.

Example: auditcfg = azn #auditcfg = authn #auditcfg = http

auditlog

Syntax

auditlog = file_name

Description

Name of the audit trail file for WebSEAL.

Options

file_name

The file name value represents an alphanumeric string.

Usage

This stanza entry is required when auditing is enabled.

Default value

aznapi_webseald-<instance_name>.log.

where:

<instance_name>

The WebSEAL instance name. For example, default.

Example

cache-refresh-interval

Syntax

cache-refresh-interval = {disable|default|number_of_seconds}

Description

Poll interval between checks for updates to the master authorization server.

Options

disable

The interval value in seconds is not set.

default

When value is to default, an interval of 600 seconds is used.

number_of_seconds

Integer value indicating the number of seconds between polls to the master authorization server to check for updates.

The minimum number of seconds is 0. There is no maximum value.

Usage

This stanza entry is optional.

Default value

disable

Example

cache-refresh-interval = disable

cred-attribute-entitlement-services

Syntax

cred-attribute-entitlement-services = service-ID

Description

Enables the credential policy entitlements service.

Options

service-ID

ID of service.

Usage

This stanza entry is optional.

Default value

TAM_CRED_POLICY_SVC

Example

cred-attribute-entitlement-services = TAM_CRED_POLICY_SVC

dynamic-adi-entitlement-services

Syntax

dynamic-adi-entitlement-services = service-ID

Description

A list of configured entitlements service IDs that are queried by the rules engine if missing ADI is detected during an authorization rule evaluation.

Options

service-ID

Service ID that is queried by the rules engine if missing ADI is detected during an authorization rule evaluation.

Usage

This stanza entry is optional.

Default value

None.

Example

dynamic-adi-entitlement-services = AMWebARS_A

input-adi-xml-prolog

Syntax

input-adi-xml-prolog = prolog

Description

The prolog to be added to the top of the XML document that is created using the Authorization Decision Information (ADI) needed to evaluate a boolean

authorization rule.

Options

prolog The prolog to be added to the top of the XML document that is created using the Authorization Decision Information (ADI) needed to evaluate a boolean authorization rule.

Usage

This stanza entry is optional.

Default value

Example

input-adi-xml-prolog = <?xml version=’1.0’ encoding=’UTF-8’?>

listen-flags

Syntax

listen-flags = {enable|disable}

Description

Enables or disables the reception by WebSEAL of policy cache update notifications from the master authorization server.

Options

enable

Activates the notification listener.

disable

Deactivates the notification listener.

Usage

This stanza entry is required.

Default value

disable

Example

listen-flags = enable

logaudit

Syntax

logaudit = {yes|true|no|false}

Description

Enables or disables auditing.

Options

yes Enable auditing.

true Enable auditing.

no Disable auditing.

false Disable auditing.

Usage

This stanza entry is required.

Default value

no

Example

logaudit = no

logclientid

Syntax

logclientid = webseald

Description

Name of the daemon whose activities are audited through use of authorization API logging.

Options

webseald

Name of the daemon whose activities are audited through use of authorization API logging.

Usage

This stanza entry is required.

Default value

webseald

Example

logclientid = webseald

logcfg

Syntax

logcfg = category:{stdout|stderr|file|remote|rsyslog}[ [parameter=value ] [,parameter=value]...]

Description

Specifies event logging for the specified category.

Options

Specifies event logging for the specifiedcategory.

For WebSEAL, the categories are:

audit.azn

Authorization events.

audit.authn

Credentials acquisition authentication.

http All HTTP logging information.

http.clf

HTTP request information as defined by the request-log-format configuration entry in the [logging] stanza.