Service Requirements

The following requirements for each service are generally done in a set of libraries for that language. These are to ensure functionality is homogeneous as our services communicate with each other. The requirements below mostly deal with attributes on logs and spans, but some are expected security practices that may be implemented in the middleware. Any $ENV variable is accessible in a container if it is deployed using the banno-k8s-operator.

Tag Header Data on Spans and Logs

We tag HTTP request and response headers onto the distributed trace spans using specific attributes, based on an allow list of header names.

• Allowed Headers:

  • If a header’s key is in the allow list, it is tagged onto the span individually.
  • Attribute Format: http.(request|response).header.(headerKey)=headerValue
  • The spec is linked here http.request.header.<key> and http.response.header.<key>

• Redacted Headers:

  • If a header’s key is not in the allow list, its key is collected and added to a single redaction attribute. The Value Type of this OTEL attribute is string[]. The actual header value is not recorded.
  • Attribute Format: http.(request|response).header_redacted_list=[headerKey1, headerKey2, ...]

Configuration

The allow list of header names is defined by the following environment variable:

• Environment Variable: $ALLOWED_HEADERS_TO_SHOW
• Format: A comma-delimited string of header names (e.g., 'a,b,c').
• Requirement: This list must be expandable within the application at runtime.
• Source: The configuration source for this environment variable can be found here.

Important Note (Change from Previous Versions)

In previous versions, all non-allowed headers were applied as individual attributes with the value <REDACTED>. This methodology is no longer used. The new aggregation approach (using redacted_list) prevents us from hitting the column limit in Honeycomb, which could occur if a user spammed random header names.

The format for these incoming request headers should follow the OTEL specification of http.request.header.$KEY. Response headers should follow the OTEL specification of http.response.header.$KEY.

The specification can be found here

Add Jack Henry Specific Headers

Clients must send the X-JH-Application-Name and X-JH-Application-Version headers with calls to internal services. X-JH-Application-Name must contain the service’s name. X-JH-Application-Version must contain the value of the application version.

Tag OTEL HTTP Attributes for Client and Server Spans

Client and Server spans are required to have the items listed here

Only Send Internal Headers to Host Allow List

Internal headers, such as X-JH-Application-Name, X-JH-Application-Version, the Consumer and Enterprise JWT, and other headers dealing with Jack Henry are forbidden from being sent outside of our network. Internal-only headers may only be sent to internal hosts that are found in the $DIGITAL_INTERNAL_HOST_SUFFIXES environment variable as a comma delimited string. I.E. 'a,b,c'.

X-Request-Id and X-Correlation-Id

The X-Request-Id and X-Correlation-Id headers are required to be generated if not present and persisted to internal services. Today, these two headers will be the same value as we use X-Request-Id in searches as though it is a X-Correlation-Id. X-Request-Id will be an attribute of the name banno.request.x_request_id and X-Correlation-Id will be an attribute of the name correlationId. These names will change as we fix how we use these headers.

Tag JWT Information for the Consumer or Enterprise JWT

The attributes for Consumer JWTs must include:

• banno.institution.id
• banno.user.id
• banno.user.name
• banno.user.ip
• banno.user.type
• banno.user.primary_login.id
• banno.user.high_risk_authorized
• banno.device.id
• banno.jwt.type
• banno.auth.type

If the following optional values appear on the JWT they should be tagged:

• banno.device.model
• banno.user.netteller.id
• banno.user.cash_management.id
• banno.user.accounts
• banno.device.model
• banno.device.browser
• banno.device.appVersion
• banno.device.os
• banno.device.broswerversion
• banno.device.brand
• banno.device.browserEngine
• banno.device.osversion

The attributes for Enterprise JWTs will include:

• banno.enterprise_user.id
• banno.enterprise_user.name
• banno.enterprise_user.ip
• banno.jwt.type
• banno.auth.type

If the affectedConsumerUser field is there it’s expected to include:

• banno.institution.id
• banno.user.id
• banno.user.name
• banno.user.type
• banno.user.primary_login.id
• banno.user.netteller.id
• banno.user.cash_management.id
• banno.user.accounts