WebSEAL Reverse Proxy Configuration

This section covers the WebSEAL configuration of a Verify Identity Access deployment. This includes configuring the reverse proxy policy server and user registry.

Administrators can also use this section to cover WebSEAL specific functionality such as HTTP transformation rules, client certificate mapping, federated user registries.

Example

webseal:
  runtime:
    policy_server: "ldap"
    user_registry: "ldap"
    ldap:
      host: "openldap"
      port: 636
      dn: !secret default/isva_secrets:ldap_bind_dn
      dn_password: !secret default/isva_secrets:ldap_bind_pw
      key_file: "lmi_trust_store"
    clean_ldap: True
    domain: "Default"
    admin_user: !secret default/isva_secrets:sec_user
    admin_password: !secret default/isva_secrets:sec_pw
    admin_cert_lifetime: 1460
    ssl_compliance: "fips"
  reverse_proxy:
  - name: "default"
    host: "isvaruntime"
    http:
      enabled: "no"
    https:
      enabled: "yes"
    domain: "Default"
    ldap:
      ssl_yn: "yes"
      port: 636
      key_file: "lmi_trust_store"
    aac_configuration:
      hostname: "isvaruntime"
      port: 9443
      junction: "/mga"
      user: !secret default/isva_secrets:runtime_user
      password: !secret default/isva_secrets:runtime_pw
      reuse_certs: True
      reuse_acls: True
    stanza_configuration:
    - stanza: "acnt-mgt"
      entry_id: "enable-local-response-redirect"
      value: "yes"
      operation: "update"
    - stanza: "local-response-redirect"
      entry_id: "local-response-redirect-uri"
      value: "/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:password"
      operation: "update"
  pdadmin:
    users:
    - name: "testuser"
      dn: !secret default/isva_secrets:test_dn
      password: !secret default/isva_secrets:test_pw

Reverse Proxy Instances

Properties to configure a WebSEAL Reverse Proxy instance. A reverse proxy instance typically defines one or more junctions to protected application servers. This section can also be used to define configuration for the webseal.conf file as well as run the integration wizards for MMFA, AAC and Federation capabilities from the Federated Runtime Server.

Stanza configuration

For each WebSEAL reverse proxy instance, administrators are able to define section/key/value entries to modify the webseal.conf file for that instance. Each stanza modification must also include an operation to either: add an entry, creating duplicate entries if the particular section/key combination already exists; update an entry if it already exists, or add it if it does not; and remove an entry if it exists.

Junction configuration

For each WebSEAL instance, administrators will typically define one or more standard or virtual junctions. Junctions are how an administrator defines the relationship and behavior between a WebSEAL server and an application server (for whom TCP traffic is being proxied by WebSEAL). Some advanced configuration options cannot be set in this entry and the Stanza configuration must be used to set key/value entries in the reverse proxy config file.

Runtime Configuration Wizards

Every WebSEAL instance can optional provide more advanced authentication and authorization logic by integrating the Advanced Access Control runtime server as an External Authentication Interface (EAI). To simplify this configuration, a number of wizards are available for Access Control<>access-control.rst#Context Based Access Control, Federations and Mobile Multi-Factor Authentication

class src.ibmvia_autoconf.webseal.WEB_Configurator.Reverse_Proxy

Note

Configuration to connect to the user registry is read from the webseal.runtime entry.

Note

Federations configured in ths step must already exist. If federations are being created and configured for WebSEAL at the same time then the reverse proxy configuration should be added to the federation configuration properties.

Example:

reverse_proxy:
- name: "default"
  host: "ibmsec.verify.access"
  listening_port: 7234
  domain: "Default"
  http:
  - enabled: "no"
  https:
  - enabled: "yes"
    port: 443
  junctions:
  - junction_point: "/app"
    description: "Backend Application"
    junction_type: "ssl"
    transparent_path: true
    server_hostname: "1.2.3.4"
    server_port: 443
    remote_http_header:
    - "iv-user"
    - "iv-groups"
    - "iv-creds"
  aac_configuration:
    hostname: "localhost"
    port: 443
    runtime:
      user: !secret default/isva-secrets:runtime_user
      password: !secret default/isva-secrets:runtime_password
    junction: "/mga"
    reuse_acls: True
    reuse_certs: True

class AAC_Configuration

class Liberty_Server

hostname: str: Hostname or address of server.

password: str: Password to use for basic authentication.

port: int: Port server is listening on.

username: str: Username to use for basic authentication.

junction: str: Junction to create.

reuse_acls: bool: Re-use existing Policy Server ACL’s

reuse_certs: bool: Re-use existing certificates in the SSL database.

runtime: Liberty_Server: Liberty runtime server properties.

class ApiProtectionConfiguration

class Liberty_Server

hostname: str: Hostname or address of server.

password: str: Password to use for basic authentication.

port: int: Port server is listening on.

username: str: Username to use for basic authentication.

api: bool | None: Should this reverse proxy be configured for API protection. Default is false.

auth_register: bool | None: Will the client registration endpoint require authentication. Default is false.

browser: bool | None: Should this reverse proxy be configured for Browser interaction. Default is false.

fapi_compliant: bool | None: Configures reverse proxy instance to be FAPI Compliant. Default is false.

junction: str: Name of the API Protection Junction.

reuse_acls: bool: Re-use existing Policy Server ACL’s

reuse_certs: bool: Re-use existing certificates in the SSL database.

runtime: Liberty_Server: Liberty runtime server properties.

class Endpoint

enabled: bool: Enable traffic on this endpoint.

port: int | None: Network port that endpoint should listen on.

class Federation_Configuration

class Liberty_Server

hostname: str: Hostname or address of server.

password: str: Password to use for basic authentication.

port: int: Port server is listening on.

username: str: Username to use for basic authentication.

name: str: Name of the Federation.

reuse_acls: bool: Re-use existing Policy Server ACL’s

reuse_certs: bool: Re-use existing certificates in the SSL database.

runtime: Liberty_Server: Liberty runtime server properties.

class Junction

authz_rules: str: Specifies whether to allow denied requests and failure reason information from authorization rules to be sent in the Boolean Rule header (AM_AZN_FAILURE) across the junction.

basic_auth_mode: str: Defines how the Reverse Proxy server passes client identity information in HTTP basic authentication (BA) headers to the back-end server.

case_sensitive_url: str: Specifies whether the Reverse Proxy server treats URLs as case sensitive.

client_ip_http: str: Specifies whether to insert the IP address of the incoming request into an HTTP header for transmission to the junctioned Web server.

cookie_include_path: str: Specifies whether script generated server-relative URLs are included in cookies for junction identification.

delegation_support: str: This option is valid only with junctions that were created with the type of ssl or sslproxy.

description: str | None: An optional description for this junction.

enable_basic_auth: str: Specifies whether to use BA header information to authenticate to back-end server. yes | no.

force: bool: Specifies whether to overwrite an existing junction of the same name.

fss_config_file: str: The name of the configuration file that is used for forms based single sign-on.

gso_resource_group: str: The name of the GSO resource or resource group.

http_port: str: HTTP port of the back-end third-party server.

https_port: str: HTTPS port of the back-end third-party server.

insert_ltpa_cookie: bool: Controls whether LTPA cookies are passed to the junctioned Web server. yes | no

insert_session_cookie: bool: Controls whether to send the session cookie to the junctioned Web server.

junction_cookie_javascript_block: str: Controls the junction cookie JavaScript block. trailer | inhead | onfocus | xhtml10 | httpheader.

junction_hard_limit: str: Defines the hard limit percentage for consumption of worker threads.

junction_point: str: Name of the location in the Reverse Proxy namespace where the root of the back-end application server namespace is mounted.

junction_soft_limit: str: Defines the soft limit percentage for consumption of worker threads.

junction_type: str: Type of junction.

key_label: str: The key label for the client-side certificate that is used when the system authenticates to the junctioned Web server.

local_ip: str: Specifies the local IP address that the Reverse Proxy uses when the system communicates with the target back-end server.

ltpa_keyfile: str: Location of the key file that is used to encrypt the LTPA cookie data.

ltpa_keyfile_password: str: Password for the key file that is used to encrypt LTPA cookie data.

mutual_auth: bool: Specifies whether to enforce mutual authentication between a front-end Reverse Proxy server and a back-end Reverse Proxy server over SSL. yes | no.

password: str: The Reverse Proxy password to send BA header information to the back-end server.

preserve_cookie: str: Specifies whether modifications of the names of non-domain cookies are to be made.

proxy_hostname: str: The TCP port of the proxy server.

proxy_port: str: The TCP port of the proxy server.

query_contents: str: Provides the Reverse Proxy with the correct name of the query_contents program file and where to find the file.

remote_http_header: List[str]: Controls the insertion of Security Verify Identity Access specific client identity information in HTTP headers across the junction.

request_encoding: str: Specifies the encoding to use when the system generates HTTP headers for junctions.

scripting_support: str: Supplies junction identification in a cookie to handle script-generated server-relative URLs.

server_cn: str: Specifies the common name, or subject alternative name, of the junctioned Web server.

server_dn: str: Specifies the distinguished name of the junctioned Web server.

server_hostname: str: The DNS host name or IP address of the target back-end server.

server_port: str: TCP port of the back-end third-party server.

server_uuid: str: Specifies the UUID that will be used to identify the junctioned Web server.

sms_environment: str: Only applicable for virtual junctions. Specifies the replica set that sessions on the virtual junction are managed under.

stateful_junction: str: Specifies whether the junction supports stateful applications. yes | no.

tfim_sso: bool: Enables IBM Security Federated Identity Manager single sign-on (SSO) for the junction. yes | no

transparent_path_junction: str: Specifies whether a transparent path junction is created. yes | no.

username: str: The Reverse Proxy user name to send BA header information to the back-end server.

version_two_cookies: str: Specifies whether LTPA version 2 cookies (LtpaToken2) are used.

vhost_label: str: Only applicable for virtual junctions. Causes a second virtual junction to share the protected object space with the initial virtual junction.

virtual_hostname: str: Virtual host name that is used for the junctioned Web server.

windows_style_url: str: Specifies whether Windows style URLs are supported.

class LDAP

cert_file: str | None: The SSL Certificate to use to verify connections. Only valid of ssl is yes.

key_file: str | None: The SSL Database to use to verify connections. Only valid if ssl is yes.

port: int: The network port to communicate with the LDAP server.

ssl: str: Enable SSL Verification of connections. yes or no

class MMFA_Configuration

class Liberty_Server

hostname: str: Hostname or address of server.

password: str: Password to use for basic authentication.

port: int: Port server is listening on.

username: str: Username to use for basic authentication.

channel: str: MMFA channel to configure. mobile | browser | both.

lmi: Liberty_Server: Liberty LMI server properties.

reuse_acls: bool: Re-use existing Policy Server ACL’s

reuse_certs: bool: Re-use existing certificates in the SSL database.

reuse_pops: bool: Re-use existing Policy Server POP’s

runtime: Liberty_Server: Liberty runtime server properties.

class Stanza_Configuration

entry_id: str | None: Optional entry name to modify.

operation: str: Operation to perform on configuration file. Valid values include add, delete and update.

stanza: str: Name of stanza to modify.

value: str | None: Optional entry value to modify.

aac_configuration: AAC_Configuration | None: Properties for configuring this reverse proxy instance for use with advanced access control authentication and context based access service.

api_protection_configuration: ApiProtectionConfiguration | None: Properties for integrating this reverse proxy with OIDC API Protection Clients.

domain: str: The Security Verify Identity Access domain.

federation_configuration: Federation_Configuration | None: Properties for integrating with a running Federation runtime.

host: str: The host name that is used by the Security Verify Identity Access policy server to contact the appliance.

http: Endpoint: HTTP traffic endpoint properties.

https: Endpoint: HTTPS traffic endpoint properties.

ip_address: str | None: The IP address for the logical interface. Only valid for appliance deployments where nw_interface_yn is yes. yes | no.

junctions: List[Junction] | None: Junctions to backend resource servers for this reverse proxy instance.

ldap: LDAP: LDAP policy server properties.

listening_port: int: This is the listening port through which the instance communicates with the Security Verify Identity Access policy server.

management_root: List[str]: List of files to import into WebSEAL hosted pages. Directory structure should be relative to the predefined top-level directories.

mmfa_configuration: MMFA_Configuration | None: Properties for configuring this reverse proxy instance to deliver MMFA capabilities.

name: str: Name of the reverse proxy instance.

nw_interface_yn: str | None: Specifies whether to use a logical network interface for the instance. Only valid for appliance deployments. yes | no.

stanza_configuration: Stanza_Configuration | None: List of modifications to perform on the webseald.conf configuration file for this reverse proxy instance.

Policy Directory Admin

Administrators can also use the pdadmin tool to modify the configured User Registry and Policy Server. This tool is used to: create Access Control Lists (ACL’s); create Protected Object Policies (POP’s); create users or groups; as well as attaching ACL’s or POP’s to a reverse proxy instance’s object space.

class src.ibmvia_autoconf.webseal.WEB_Configurator.PD_Admin

Note

Configuration to connect to the user registry is read from the webseal.runtime entry.

Example:

pdadmin:
  users:
    - username: "testuser"
      password: !secret default/isva-secrets:test_password
      dn: "cn=testuser,dc=iswga"
    - username: "aaascc"
      password: !secret default/isva-secrets:aac_user_password
      dn: "cn=aaascc,dc=iswga"
    - username: "ob_client"
      password: !secret default/isva-secrets:ob_client_password
      dn: "cn=ob_client,dc=iswga"
  reverse_proxies:
    - host: "isva-wrp"
      instance: "default-proxy"
      acls:
        - name: "isam_mobile_anyauth"
          junctions:
            - "/mga/sps/authsvc"
            - "/mga/sps/apiauthsvc"
            - "/intent/account-requests"
        - name: "isam_mobile_rest_unauth"
          junctions:
            - "/mga/websock/mmfa-wss/"
            - "/mga/sps/ac/info.js"
            - "/mga/sps/ac/js/info.js"
            - "/mga/sps/ac"
            - "/.well-known"
            - "/CertificateManagement/.well-known"
            - "/mga/sps/mmfa/user/mgmt/qr_code"
            - "/intent"
        - name: "isam_mobile_unauth"
          junctions:
            - "/login"
            - "/content"
            - "/static"
            - "/home"
            - "/ob/sps/auth"
        - name: "isam_mobile_rest"
          junctions:
            - "/scim"
      pops:
        - name: "oauth-pop"
          junctions:
            - "/scim"
    - host: "default-proxy-mobile"
      acls:
        - name: "isam_rest_mobile"
          junctions:
            - "/scim"
        - name: "isam_mobile_rest_unauth"
          junctions:
            - "/mga/sps/mmfa/user/mgmt/qr_code"
      pops:
        name: "oauth-pop"
        junctions:
          - "scim"

class Access_Control_List

class Attribute

name: str: Name of the ACL attribute

value: str: Value of the ACL attribute.

class Entity

name: str: User or Group entity to set permissions for.

permissions: str: Permission bit-string, eg. Tcmdbsvarxl

any_other: str: Permissions applied to users who do not match any of the defined user/group permissions.

attributes: List[Attribute] | None: List of extended attributes to add to ACL.

description: str | None: Optional description of the ACL

groups: List[Entity] | None: List of groups and the permissions they are permitted to perform.

name: str: Name of the ACL.

unauthenticated: str: Permissions applied to unauthenticated users.

users: List[Entity] | None: List of users and the permissions they are permitted to perform.

class Group

description: str | None: Optional description of group.

dn: str: The DN LDAP attribute for this group.

name: str: The CN LDAP attribute for this group.

users: List[str] | None: Optional list of users to add to group. These users must already exist in the user registry.

class Protected_Object_Policy

class Attribute

name: str: Name of the POP attribute.

value: str: value of the POP attribute.

class IP_Authorization

class Network

auth_level: str: Required step-up authentication level.

netmask: str: The corresponding netmask to apply to this POP.

network: str: TCP/IP address to apply to this POP.

any_other_network: str: Permissions for IP authentication not explicitly listed in the POP.

networks: List[Network] | None: List of IP addresses to perform IP endpoint authentication.

attributes: List[Attribute] | None: List of extended attribute to add to POP.

audit_level: str: Sets the audit level for the specified POP.

description: str | None: Optional description of the POP.

ip_auth: List[IP_Authorization] | None: Sets the IP endpoint authentication settings in the specified POP.

name: str: Name of the POP.

tod_access: str: Sets the time of day range for the specified protected object policy.

class Reverse_Proxy

class Reverse_Proxy_ACL

junctions: List[str]: List of junction paths which use the specified ACL.

name: str: Name of the ACL to attach to resources.

class Reverse_Proxy_POP

junction: str: List of junction paths which use the specified POP.

name: str: Name of the POP to attach to resources.

acls: List[Reverse_Proxy_ACL] | None: List of ACL’s to attach to reverse proxy instance.

host: str: Hostname use by the reverse proxy in the Policy Server’s namespace.

instance: str: WebSEAL instance name if the Policy Server’s namespace.

pops: List[Reverse_Proxy_POP] | None: List of POP’s to attach to reverse proxy instance.

class User

dn: str: The DN LDAP attribute for this user.

first_name: str | None: The CN LDAP attribute for this user. If not set then username will be used.

last_name: str | None: The SN LDAP attribute for this user. If not set then username will be used.

password: str: The secret to authenticate as username.

username: str: The name the user will authenticate as. By default this is the UID LDAP attribute.

class WebSEALObject

class Attribute

key: str: Name of the attribute to attach to the junction object.

value: str: Value of the attribute to attach to the junction object.

attributes: List[Attribute]: List of attributes to add to junction object.

hostname: str: Hostname use by the reverse proxy in the Policy Server’s namespace.

instance: str: WebSEAL instance name if the Policy Server’s namespace.

junction: str: WebSEAL junction to modify.

acls: List[Access_Control_List] | None: List of ACL’s to create in the Policy Server.

groups: List[Group] | None: List of groups to add to the User Registry. These will be created as “full” Verify Identity Access groups.

objects: List[WebSEALObject] | None: List of objects to attach attributes to.

pops: List[Protected_Object_Policy] | None: List of POP’s to create in the Policy Server.

reverse_proxies: List[Reverse_Proxy] | None: List of ACL’s and POP’s to attach to a WebSEAL reverse proxy instance.

users: List[User] | None: List of users to add to the User Registry. These will be created as “full” Verify Identity Access users.

Client certificate mapping

Client certificate mapping can be used by a reverse proxy to map X500 Name attribute from a client certificate (part of a mutual TLS connection) to authenticate a user as an identity from the User Registry. These mapping rules are written in XSLT. A rule is read from a file and uploaded to an appliance, where the resulting rule name is the filename minus the XSLT extension. A complete list of the available configuration properties can be found here. An example configuration is:

class src.ibmvia_autoconf.webseal.WEB_Configurator.Client_Certificate_Mapping

Example:

client_cert_mapping:
- demo.mapping.xslt
- cert_to_uid.xlst

client_cert_mapping: List[str]: List of XSLT files to for matching X509 certificates from an incoming connection to an entity in the User Registry.

Junction Mapping

A Junction mapping table maps specific target resources to junction names. Junction mapping is an alternative to cookie-based solutions for filtering dynamically generated server-relative URLs. A rule is read from a file and uploaded to a Verify Identity Access deployment. The name of the file which contains the junction mapping config is the resulting rule name in Verify Identity Access. An example configuration is:

class src.ibmvia_autoconf.webseal.WEB_Configurator.Junction_Mapping

Example:

junction_mapping:
- demo.jct.map
- another.jct.map

junction_mapping: List[str]: List of properties file to map URI’s to WebSEAL’s object space.

URL Mapping

A URL mapping table is used to map WebSEAL access control lists (ACLs) and protected object policies (POPs) to dynamically generated URLs, such as URLs with query string parameters. URLs can be matched using a subset of UNIX shell pattern matching (including wildcards). A complete list of supported regex can be found here

class src.ibmvia_autoconf.webseal.WEB_Configurator.Url_Mapping

Examples:

url-mapping:
- dyn.url.conf
- url.map.conf

url_mapping: List[str]: List of configuration files to re-map URL’s.

User Mapping

User mapping can be used to modify or enrich an authenticated user’s credential data. This can be used to both switch the identity of a user or add attributes to a user’s existing credential. User mapping rules are added to a Verify Identity Access deployment using XLST rules. Detailed information about user mapping XSLT configuration can be found here. The name of the XSLT file will be used as the name of the user mapping rule.

class src.ibmvia_autoconf.webseal.WEB_Configurator.User_Mapping

Example:

user_mapping:
- add_email.xslt
- federated_identity_to_basic_user.xslt

user_mapping: List[str]: List of XSLT files to be uploaded as user mapping rules.

Forms Based Single Sign-On

The FSSO (forms single sing-on) module can be used by WebSEAL to authenticate a user to a junctioned application server. The module is capable of intercepting authentication requests from an application server, and then supplying the required identity information (retrieved from either the WebSEAl user registry or a HTTP service) to the application server to complete the authentication challenge. More detailed information about FSSO concepts can be found here. The name of the FSSO configuration file will be used as the name of the resulting FSSO configuration in Verify Identity Access.

class src.ibmvia_autoconf.webseal.WEB_Configurator.Form_Single_Sign_On

Example:

fsso:
- liberty_jsp_fsso.conf
- fsso.conf

fsso: List[str]: List of configuration files to be uploaded as Form Single Sign-On rules.

HTTP Transformation Rules

HTTP transformation rules allow WebSEAL to inspect and rewrite request and response objects as they pass through the reverse proxy. HTTP transforms can be applied: when the request is received (by WebSEAL); after an authorization decision has been made; and when the response is received (by WebSEAL). Prior to Verify Access 10.0.4.0 only XSLT rules were supported, from 10.0.4.0 onwards, LUA scripts can also be used to write HTTP transforms. Detailed information about HTTP transformation concepts can be found here. The name of the HTTP transform file will be used as the name of the resulting HTTP transformation rule in Verify Identity Access.

class src.ibmvia_autoconf.webseal.WEB_Configurator.Http_Transformations

Example:

http_transforms:
  requests:
  - inject_header.xslt
  lua:
  - eai.lua

lua: List[str]: List of files to be uploaded as LUA HTTP Transformation Rules.

requests: List[str]: List of files to be uploaded as XSLT request HTTP Transformation Rules.

responses: List[str]: List of files to be uploaded as XSLT response HTTP Transformation Rules.

Kerberos

The SPNEGO/Kerberos module can be used to enable SSO solutions to Microsoft (Active Directory) systems via Kerberos delegation. Kerberos is configured by setting properties by id and subsections. There are several top level id’s which can be used to configure Kerberos Realms, Local Domain Realms, Certificate Authority paths and key files. An example configuration is:

class src.ibmvia_autoconf.webseal.WEB_Configurator.Kerberos

Example:

kerberos:
  libdefault:
    default_realm: "test.com"
  realms:
  - name: "test.com"
    properties:
    - kdc: "test.com"
  domain_realms:
  - name: "demo.com"
    dns: "test.com"
  keytabs:
  - admin.keytab
  - user.keytab

class Domain_Realm

dns: str: DNS server for the Domain Realm.

name: str: Name of the Domain Realm.

class Realm

name: str: Name of the Kerberos realm.

properties: List[Dict] | None: List of key / value properties to configure for realm.

capaths: Dict: TODO.

domain_realms: List[Domain_Realm] | None: List of Kerberos DOmain Realm’s to configure.

keytabs: List[str] | None: List of files to import as Kerbros Keytab files.

libdefaults: List[Dict] | None

value properties to configure as defaults.

Type:: List of key

realms: List[Realm] | None: List of Kerberos Realm’s to configure.

Password Strength Rules

The password strength module can be used to enforce XLST defined password requirements for basic and full Verify Identity Access users. More detailed information about rule syntax can be found here. Rules are uploaded to a deployment from files, the name of the file is used as the resulting password strength rule in Verify Identity Access. An example configuration is:

class src.ibmvia_autoconf.webseal.WEB_Configurator.Password_Strength

Example:

password_strength:
- demo_rule.xlst

RSA SecurID Authenticaton

The RSA integration module can be used to allow users who are authenticating to WebSEAL’s user registry to use a RSA OTP as a second factor. More information about configuring this mechanism and the correcsponding configuration to integrate with WebSEAL login can be found here. An example configuration is:

class src.ibmvia_autoconf.webseal.WEB_Configurator.RSA

Example:

rsa_config:
  server_config: server.conf
  optional_server_config: optional_server.conf

optional_server_config: str: The server configuration options file to upload.

server_config: str: The server configuration file to upload.

Runtime Component

The WebSEAL runtime server is the Directory Server which contains the reverse proxy’s user registry and policy server. This is typically a LDAP server external to the deployment, however an example LDAP server is made available to deployments for testing.

The Verify Identity Access specific LDAP schemas can be found in the System -> File Downloads section of an appliance/configuration container in the isva directory.

Any PKI required to verify this connection should be imported into a SSL database before the runtime component is configured.

class src.ibmvia_autoconf.webseal.WEB_Configurator.Runtime

Example:

runtime:
  policy_server: "remote"
  user_registry: "remote"
  ldap:
    host: "openldap"
    port: 636
    dn: "cn=root,secAuthority=Default"
    dn_password: @secrets/isva-secrets:ldap-passwd
    key_file: "lmi_trust_store"
  clean_ldap: True
  domain: "Default"
  admin_password: @secrets/isva-secrets:secmaster-passwd
  admin_cert_lifetime: 1460
  ssl_compliance: "FIPS 140-2"
  isam:
    host: "isvaconfig"
    port: 443
  stanza_configuration:
  - operation: "update"
    resource: "ldap.conf"
    stanza: "bind-credentials"
    entry: "bind-dn"
    value: "cn=root,secAuthority=Default"
  - operation: "delete"
    resource: "ldap.conf"
    stanza: "server:MyFederatedDirectory"

class ISAM

host: str: Hostname or address of Verify Identity Access policy server.

port: int: Port that Verify Identity Access policy server is listening on.

class LDAP

cert_label: str: SSL Certificate label to verify connections to LDAP server.

dn: str: Distinguished mane to bind to LDAP server for admin operations.

dn_password: str: Password to authenticate as dn.

host: str: Hostname or address for LDAP server.

key_file: str: SSL Database to use to verify connections to LDAP server.

port: int: Port LDAP server is listening on.

suffix: str: SecAuthority suffix.

class Stanza_Configuration

entry: str | None: Optional entry_id to modify.

operation: str: Operation to perform on configuration file. add | delete | update.

resource: str: Filename to be modified. ldap.conf | pd.conf | instance.conf.

stanza: str: Name of stanza to modify.

value: str | None: Optional value to modify.

admin_cert_lifetime: int: The lifetime in days for the SSL server certificate.

admin_password: str: The password for the sec_master user.

clean_ldap: bool: Remove any existing user data from registry. Only valid if user_registry is local.

isam: ISAM | None: Verify Identity Access policy server properties.

isam_domain: str: The Security Verify Identity Access domain name.

ldap: LDAP: LDAP server properties.

override_config: bool | None: Optional property to attempt to force a reconfiguration of the runtime component if it is already configured. This is not possible if there are reverse proxy objects. Default is false

policy_server: str: The mode for the policy server. local | remote.

ssl_compliance: str: Specifies whether SSL is compliant with any additional computer security standard. fips | sp800-131-transition | sp800-131-strict | suite-b-128 | suite-b-192.

stanza_configuration: List[Stanza_Configuration] | None: Optional list of modifications to configuration files.

user_registry: str: Type of user registry to use. local | ldap.

API Access Control

Properties to configure an API Authorization Server. An API authorization server typically defines one or more resource servers which have authentication requirements to permit access. This section can also be used to configure Cross-Origin Resource Sharing (CORS) policies.

Authorization Server

Authorization servers are the points of contact for external traffic to access protected resource servers. Each server has its own object space in the Verify Identity Access policy server.

Resource Servers

Resource servers are third party application servers / microservices that are being protected by the Authorization server.

Document Root

The document root defines a static set of web files (HTML, JS, CSS, ect.) which can be served by the Authorization server.

Cross-Origin Resource Sharing

The CORS properties can be used to configure the URI’s which are permitted to make cross-origin resource requests as well as the types of resources which are permitted to be shared.

class src.ibmvia_autoconf.webseal.WEB_Configurator.Api_Access_Control

Note

Configuration to connect to the user registry is read from the webseal.runtime entry.

Example:

api_access_control:
  authorization_servers:
  - name: "api_server"
    hostname: "localhost"
    auth_port: 9443
    admin_port: 7138
    domain: "Deafult"
    addresses:
    - "192.168.42.102"
    ssl: "yes"
    ssl_port: 636
    key_file: "pdsrv.kdb"
    key_alias: "webseal-cert"
  resource_servers:
  - name: "authz_server"
    hostname: "isvaruntime"
    junction_point: "/scim"
    junction_type:"SSL"
    authentication:
      type: "oauth"
      oauth_introspection:
        transport: "both"
        auth_method: "client_secret_basic"
        endpoint: "external.com/oauth"
        client_id: !secret default/isva-secrets:apiac_authz_client_id
        mapped_id: "{iss}/{sub}"
        external_user: true
        response_attributes:
        - pos: 0
          action: "put"
          attribute: "test_attribute"
      jwt:
        header_name: "iv-jwt"
        certiciate: "cert"
        claims:
        - type: "attr"
          value: "AZN_CRED_PRINCIPAL_NAME"
          claim_name: "sub"
    document_root:
    - webseal_root.zip
    resources:
    - name: "api_ac_instance"
      hostname: "ibmsec.verify.access"
  cors:
  - name:
    allowed_origins:
    - "https://webseal.ibm.com"
    - "https://webseal.ibm.com:9443"
    - "http://static.webseal.ibm.com"
    - "http://static.webseal.ibm.com:9080"
    allowed_credentials: true
    exposed_headers:
    - "X-ISAM-VERSION"
    - "X-ISAM-KEY"
    handle_preflight: true
    allowed_methods:
    - "retry"
    - "IBMPost"
    - "Remove"
    allowed_headers:
    - "X-ISAM-MODE"
    - "Content-type"
    max_age: 86400

class Authorization_Server

addresses: List[str] | None: A json array containing a list of local addresses on which the authorization server will listen for requests.

admin_port: int: The port on which Security Verify Identity Access administration requests will be received.

auth_port: int: The port on which authorization requests will be received.

domain: str: The Security Verify Identity Access domain.

hostname: str: The host name of the local host. This name is used when constructing the authorization server name.

key_file: str: The name of the keyfile that will be used when communicating with the LDAP server over SSL.

key_label: str: The label of the certificate within the keyfile to use.

name: str: This is the new instance name, which is a unique name that identifies the instance.

ssl: str: Whether or not to enable SSL between the Security Verify Identity Access authorization server and the LDAP server.

ssl_port: str: The SSL port on which the LDAP server will be contacted. Only valid if ssl set to yes.

class Cross_Origin_Resource_Sharing

allow_credentials: bool | None: Controls whether or not the Access-Control-Allow-Credentials header will be set. If not present, this value will default to false.

allowed_headers: List[str] | None: Controls the headers permitted in pre-flight requests and the subsequent Access-Control-Allow-Headers header. This option only relates to pre-flight requests handled by the Reverse Proxy and will be ignored if handle_preflight is set to false.

allowed_methods: List[str] | None: Controls the methods permitted in pre-flight requests and the subsequent Access-Control-Allow-Methods header. This option only relates to pre-flight requests handled by the Reverse Proxy and will be ignored if handle_preflight is set to false. Methods are case sensitive and simple methods (ie. GET, HEAD and POST) are always implicitly allowed.

allowed_origin: List[str] | None: An array of origins which are allowed to make cross origin requests to this resource. Each origin must contain the schema and any non-default port information. A value of * indicates that any origin will be allowed.

exposed_headers: List[str] | None: Controls the values populated in the Access-Control-Expose-Headers header.

handle_preflight: bool | None: Controls whether or not the Reverse Proxy will handle pre-flight requests. If not present, this value will default to false.

max_age: int | None: Controls the Access-Control-Max-Age header added to pre-flight requests. If set to zero, the header will not be added to pre-flight responses. If set to -1, clients will be told not to cache at all. If not present, this value will default to 0.

name: str: The name of the CORS policy.

class Policy

attributes: List[str] | None: The attribute matches referenced by this policy. Each attribute must be matched for this policy to be authorised. The default is no attributes if not specified.

groups: List[str] | None: The groups referenced by this policy. User must be a member of at least one group for this policy to be authorised. The default is no groups if not specified.

name: str: The name of the policy.

class Resource_Server

class Attribute

action: str: The action to perform for this attribute. Valid values are put and remove.

attribute: str: The name of the attribute.

pos: str: The position of this attribute in the ordered list of all attributes.

class Claim

claim_name: str: The name of the claim that is added to the JWT. For attr type claims this is optional and if not specified the claim name will be set as the name of the credential attribute. If the type is attr and the value contains a wildcard this field is invalid and if specified will result in an error.

type: str: The type of claim to add to the JWT. Valid values are either text for a literal text claim or attr for a credential attribute claim.

value: str: The value for the claim. If the type is text this will be the literal text that is added to the JWT. If the type is attr this will be the name of the credential attribute to add to the JWT.

class Policy

name: str | None: The name of the custom policy if the type is custom.

type: str: The type of Policy. The valid values are unauthenticated, anyauthenticated, none, default or custom.

class Resource

class Response_Header

name: str: The name of the response header.

value: str: The value of the response header.

doc_file: str: The name and path of the documentation file to respond with, relative to the junction root.

doc_type: str: The value of the accept header that will trigger a documentation response.

method: str: The HTTP action for this resource.

name: str | None: A description for this resource.

path: str: The URI path for this resource. This is a full server relative path including the junction point.

policy_name: str: The name of the custom policy if the type is custom.

policy_type: str: The type of Policy. The valid values are unauthenticated, anyauthenticated, none, default or custom.

rate_limiting_policy: str | None: The name of the rate limiting policy that has been set for this resource.

static_response_headers: List[Response_Header] | None: A list of header names and values that should be added to the HTTP response.

url_aliases: List[str] | None: A list of aliases that all map to the path of this resource.

class Response_Header

name: str: The name of the response header.

value: str: The value of the response header

authentication_type: str: The type of Oauth authentication. The valid values are default or oauth.

authz_rules: str: Specifies whether to allow denied requests and failure reason information from authorization rules to be sent in the Boolean Rule header (AM_AZN_FAILURE) across the junction. Valid value is yes or no.

basic_auth_mode: str | None: Defines how the Reverse Proxy server passes client identity information in HTTP basic authentication (BA) headers to the back-end server. Valid value include filter (default), ignore, supply and gso.

case_sensitive_url: str: Specifies whether the Reverse Proxy server treats URLs as case sensitive. Valid value is yes or no.

client_ip_http: str: Specifies whether to insert the IP address of the incoming request into an HTTP header for transmission to the junctioned Web server. Valid value is yes or no.

cookie_include_path: str: Specifies whether script generated server-relative URLs are included in cookies for junction identification. Valid value is yes or no.

delegation_support: str | None: This option is valid only with junctions that were created with the type of ssl or sslproxy. Indicates single sign-on from a front-end Reverse Proxy server to a back-end Reverse Proxy server.

description: str | None: An optional description for this junction.

document_root: List[str] | None: List of documents to upload to the document root.

enable_basic_auth: str: Specifies whether to use BA header information to authenticate to back-end server. Valid value is yes or no.

force: str: Specifies whether to overwrite an existing junction of the same name. Valid value is yes or no.

fsso_config_file: str: The name of the configuration file that is used for forms based single sign-on.

gso_respource_group: str | None: The name of the GSO resource or resource group.

http2_junction: str | None: Specifies whether the junction supports the HTTP/2 protocol. By default, junctions do not support the HTTP/2 protocol. A valid value is yes or no.

http2_proxy: str | None: Specifies whether the junction proxy support the HTTP/2 protocol. By default, junction proxies do not support the HTTP/2 protocol. A valid values are yes or no.

http_port: int: HTTP port of the back-end third-party server. Applicable when the junction type is tcp.

https_port: int: HTTPS port of the back-end third-party server. Applicable when the junction type is ssl.

insert_ltpa_cookies: str: Controls whether LTPA cookies are passed to the junctioned Web server. Valid value is yes or no.

insert_session_cookies: str: Controls whether to send the session cookie to the junctioned Web server. Valid value is yes or no.

junction_cookie_javascript_block: str: Controls the junction cookie JavaScript block. The value should be one of trailer, inhead, onfocus or xhtml10.

junction_hard_limit: str: Defines the hard limit percentage for consumption of worker threads. Valid value is an integer from 0 to 100.

junction_point: str: Name of the location in the Reverse Proxy namespace where the root of the back-end application server namespace is mounted.

junction_soft_limit: str: Defines the soft limit percentage for consumption of worker threads. Valid value is an integer from 0 to 100.

junction_type: str: Type of junction. Valid values include tcp, ssl, tcpproxy, sslproxy and mutual.

jwt_certificate: str | None: The label of the personal certificate that will sign the JWT.

jwt_claims: Claim | None: The list of claims to add to the JWT.

jwt_header_name: str | None: The name of the HTTP header that will contain the JWT.

key_label: str | None: The key label for the client-side certificate that is used when the system authenticates to the junctioned Web server.

local_ip: str | None: Specifies the local IP address that the Reverse Proxy uses when the system communicates with the target back-end server.

ltpa_keyfile: str | None: Location of the key file that is used to encrypt the LTPA cookie data.

ltpa_keyfile_password: str | None: Password for the key file that is used to encrypt LTPA cookie data.

mutual_auth: str: Specifies whether to enforce mutual authentication between a front-end Reverse Proxy server and a back-end Reverse Proxy server over SSL. Valid value is yes or no.

oauth_introspection_auth_method: str | None: The method for passing the authentication data to the introspection endpoint. Valid values are client_secret_basic or client_secret_post.

oauth_introspection_client_id: str | None: The client identifier which is used for authentication with the external OAuth introspection endpoint.

oauth_introspection_client_id_hdr: str | None: The name of the HTTP header which contains the client identifier which is used to authenticate to the introspection endpoint. Only valid if client_id has not been set.

oauth_introspection_client_secret: str | None: The client secret which is used for authentication with the external OAuth introspection endpoint.

oauth_introspection_endpoint: str | None: This is the introspection endpoint which will be called to handle the token introspection.

oauth_introspection_external_user: str | None: A boolean which is used to indicate whether the mapped identity should correspond to a known Verify Identity Access identity or not.

oauth_introspection_mapped_id: str | None: A formatted string which is used to construct the Verify Identity Access principal name from elements of the introspection response. Claims can be added to the identity string, surrounded by {}.

oauth_introspection_proxy: str | None: The proxy, if any, used to reach the introspection endpoint.

oauth_introspection_response_attributes: List[Attribute]: A list of rules indicating which parts of the json response should be added to the credential.

oauth_introspection_token_type_hint: str | None: A hint about the type of the token submitted for introspection.

oauth_introspection_transport: str | None: The transport type. The valid values are none, http, https or both.

password: str | None: The Reverse Proxy password. Used to send BA header information to the back-end server.

policy: Policy: The Policy that is associated with this Resource Server.

preserve_cookie: str | None: Specifies whether modifications of the names of non-domain cookies are to be made. Valid value is yes or no.

proxy_hostname: str | None: The DNS host name or IP address of the proxy server. Applicable when the junction type is sslproxy.

proxy_port: int | None: The TCP port of the proxy server. Applicable when the junction type is tcpproxy.

query_contents: str: Provides the Reverse Proxy with the correct name of the query_contents program file and where to find the file. By default, the Windows file is called query_contents.exe and the UNIX file is called query_contents.sh.

remote_http_header: List[str] | None: Controls the insertion of Security Verify Identity Access specific client identity information in HTTP headers across the junction. The value is an array containing a combination of iv-user, iv-user-l, iv-groups, iv-creds or all.

request_encoding: str: Specifies the encoding to use when the system generates HTTP headers for junctions. Possible values for encoding include utf8_bin, utf8_uri, lcp_bin, and lcp_uri.

resources: List[Resource] | None: List of resources to add to resource server.

reverse_proxy: str: Name of the WebSEAL Reverse Proxy instance this resource server is attached to.

scripting_support: str | None: Supplies junction identification in a cookie to handle script-generated server-relative URLs.

server_dn: str | None: Specifies the distinguished name of the junctioned Web server.

server_hostname: str: The DNS host name or IP address of the target back-end server.

server_port: int: TCP port of the back-end third-party server. Default is 80 for TCP junctions and 443 for SSL junctions.

sever_cn: str | None: Specifies the common name, or subject alternative name, of the junctioned Web server.

sms_environment: str | None: Only applicable for virtual junctions. Specifies the replica set that sessions on the virtual junction are managed under.

sni_name: str | None: The server name indicator (SNI) to send to TLS junction servers. By default, no SNI is sent.

stateful_junction: str | None: Specifies whether the junction supports stateful applications. By default, junctions are not stateful. Valid value is yes or no.

static_response_headers: List[Response_Header]: A list of header names and values that should be added to the HTTP response. List of key value pairs eg. {"name":"Access-Control-Max-Age", "value":"600"}

tfim_sso: str: Enables IBM Security Federated Identity Manager single sign-on (SSO) for the junction. Valid value is yes or no.

transparent_path_junction: str: Specifies whether a transparent path junction is created. Valid value is yes or no.

username: str | None: The Reverse Proxy user name. Used to send BA header information to the back-end server.

version_two_cookies: str | None: Specifies whether LTPA version 2 cookies (LtpaToken2) are used. Valid value is yes or no.

vhost_label: str | None: Only applicable for virtual junctions. Causes a second virtual junction to share the protected object space with the initial virtual junction.

virtual_hostname: str | None: Virtual host name that is used for the junctioned Web server.

windows_style_url: str: Specifies whether Windows style URLs are supported. Valid value is yes or no.

authorization_servers: List[Authorization_Server] | None: List of API Authorization servers to create.

cors: List[Cross_Origin_Resource_Sharing] | None: List of Cross-Origin Resource Sharing policies to create.

policies: List[Policy] | None: List of API access control policies to create.

resource_servers: List[Resource_Server] | None: List of API Resource servers to create.