SIP2-277 - IP Address Elimination Options

Tenant matching in edge-sip2 is performed at connection time using configuration from sip2-tenants.conf. When a SIP2 client connects, the server determines the tenant in two steps:

1. Port-based matching: If a tenant config in scTenants has a port that matches the connection’s port, that tenant is selected.

2. Subnet/IP-based matching: If no tenant matches by port, the client’s IP is checked against the scSubnet ranges defined for each tenant; the first matching subnet determines the tenant.

This priority ensures dedicated ports can be mapped to tenants directly, while a fallback to subnet/IP is possible for shared ports. If no match is found, a default config is used. These checks are handled by TenantUtils.lookupTenantConfigForIpAddress() in the backend code. Hostname-based matching is not supported.

In edge-sip2, port-based tenant matching enables the system to determine the correct tenant configuration for each incoming client connection based solely on the TCP port number the client connects to.

How it works:

• Tenant configurations reside in sip2-tenants.conf under the scTenants array. Each tenant object in this array may specify a "port" value.

• During startup, MainVerticle reads the configuration and starts a separate server (NetServer) for each configured port.

• When a client connects, edge-sip2 uses the actual port number of the incoming connection to identify the tenant.

• The method TenantUtils.lookupTenantConfigForIpAddress is called with the port number and searches for a tenant configuration entry with a matching "port" property.

• If a tenant configuration with the specified port is found, that tenant’s settings are applied to the session. This includes configuration such as SIP2 protocol options, message delimiters, character sets, and error handling preferences.

• Port matching is prioritized over any other matching rules (subnet, fallback), making it deterministic and simple - each port is mapped to at most one tenant.

• If no tenant is defined for the port, tenant identification falls back to other configured criteria (e.g., subnet), though those are not considered in port-based matching.

When multiple tenants share the same port and username-based prefixing is not used, edge-sip2 can identify the correct tenant by attempting to authenticate the provided login credentials (username and password) against each tenant configuration. Upon receiving a SIP2 login request, the server iterates through all configured tenants, performing a login for each. The first tenant for which authentication succeeds is selected, and all subsequent session operations use this tenant context. If none authenticate successfully, the login attempt is rejected.

• Single Port: You can serve all tenants via a single port, simplifying deployments.

• Flexibility: New tenants can be added just by updating the username→tenant mapping and config.

• Security: You must maintain a secure mapping from usernames to tenants and make sure credentials cannot clash between tenants.

• Initial Complexity: Requires careful state handling; before the login message is processed, the tenant details are unknown.

• Performance: Many login operations. For large installations, this could be slow.

Clients include the tenant code as a prefix to the username, separated by a double underscore (e.g., tenantA__john). When a login request is received, the server extracts the tenant prefix to select the matching tenant configuration and then authenticates with the remainder of the username. This ensures accurate and secure tenant detection on shared ports without additional infrastructure or protocol changes. Using the username prefix method avoids ambiguous logins and eliminates the need for multi-tenant credential brute-forcing. Clients must use the agreed prefix format for successful login and tenant selection.

• Single Port: You can serve all tenants via a single port, simplifying deployments.

• No guesswork: No need to brute-force creds across tenants.

• Scalable: Works with any number of tenants.

• Secure: Prevents ambiguity and accidental credential leaks.

• Minimal changes: Still works with a single service port.

• Update Client Practice: Instruct all clients to use usernames with a tenant prefix (e.g., tenant1__sip2user, tenantA__sip2user).

• Modify Login Handler:

  • On receiving the SIP2 login (93) message, extract the prefix and look up the tenant config by that token.

  • Use only the remainder of the username for authentication to the ILS.

Tenant routing based on the SNI (Server Name Indication, i.e., the hostname sent in the TLS handshake) is not supported in edge-sip2’s current implementation. While Vert.x and Netty can use SNI to select the correct SSL certificate, the chosen hostname is not made available to application code, and cannot be accessed for tenant selection in message or session handlers. Therefore, SNI-based tenant detection is not possible with the present architecture.

Tenant routing using information from client TLS certificates is not supported in edge-sip2’s current codebase. Although Vert.x supports verifying and authenticating client certificates, it does not expose the client certificate’s details at the application level within TCP socket handlers. As a result, there is no mechanism to select or map tenants based on the client certificate in the current implementation.

This is a practical approach for tenant determination in environments where the SIP2 login request reliably includes the location code (CP). By maintaining a mapping between location codes and tenant identifiers in the configuration module, the system can resolve the tenant context at login time.

• A configuration property is introduced to store a mapping of locationCode → tenantId.

• Upon receiving a SIP2 login, the server extracts the CP (location code) from the request.

• The location code is used to look up the corresponding tenant identifier.

• The identified tenant’s configuration is then loaded and used for the session.

• Location code mapping can be part of scTenants object value

• Enables tenant detection using information already available in the protocol.

• Does not require port/IP segregation or username conventions.

• Reduces the risk of credential ambiguity since mapping is explicit and not dependent on user input patterns.

• Correctness relies on clients sending appropriate and unique location codes as part of the login.

• Care must be taken to keep the location/tenant mapping up to date to reflect operational changes.

• If multiple tenants share location codes or if codes are reused, ambiguity may arise.

• scTenants will contain locationCodes fields with all related identifiers

• locationCode is unique per kiosk

Implement a configurable lookup based on provided methods, which can be specified per module as a comma-separated value of lookup types

• edge-sip2 offers several strategies for tenant identification, with port-based and IP/subnet-based matching as core, production-ready solutions. Port-based matching is robust, easy to administer, and already implemented, making it the recommended approach for most multi-tenant deployments.

• When port sharing is required, username prefixing and location code (CP) lookup are a secure and scalable alternative, enabling accurate tenant selection without compromising credential integrity.

  • Username prefix and location code lookup strategies are simple to implement.

  • Login credential trials add complexity and potential security risks due to overlapping credentials and increased authentication attempts. This option is excluded from implementation

• Hostname-based routing via SNI and client certificate-based routing are not supported in the current implementation, as Vert.x does not expose SNI or certificate details to application handlers within TCP connections. For secure and maintainable multi-tenancy, organizations are advised to use port-based or username prefix strategies, with careful configuration and client coordination.