1 Configuration Reference
- 1.1 Overview
- 1.2 File Location
- 1.3 File Structure
- 1.4 Route Configuration
  - 1.4.1 URL Pattern Matching
  - 1.4.2 Route Example
- 1.5 Connection Types
  - 1.5.1 OAUTH20
  - 1.5.2 OAUTH20_CLIENT_CREDENTIALS
  - 1.5.3 OAUTH10A
  - 1.5.4 FIXED_HEADERS
  - 1.5.5 BEARER_TOKEN_FORWARD
- 1.6 Environment Variable Substitution
- 1.7 Complete Example

Configuration Reference

This document is the complete configuration reference for the Connection Routing Spring Boot Starter. It covers the connection-routing.yml file that defines authentication routes and connection definitions, as well as the Spring Boot application properties that control runtime behavior.

Overview

Connection Routing automatically injects authentication headers into outbound HTTP requests made through its WebClient. You define routes that match requests by URL pattern and HTTP method, and link each route to a connection that specifies the authentication mechanism (OAuth 2.0, OAuth 1.0a, fixed headers, or bearer token forwarding).

When an outgoing request matches a route, the library transparently handles token acquisition, storage, refresh, and header injection.

File Location

The library looks for connection-routing.yml in the following order:

Working directory -- ./connection-routing.yml
Classpath -- classpath:connection-routing.yml (e.g., src/main/resources/connection-routing.yml)

If the file is not found in either location, the application will fail to start with an IllegalArgumentException.

File Structure

The configuration file has two top-level sections:

connection-routing:   # List of route definitions
  - connection-id: my-api
    methods: ALL
    root-uris:
      - https://api.example.com/**

connections:          # Map of connection definitions (keyed by connection-id)
  my-api:
    connection-type: OAUTH20
    # ... type-specific properties

connection-routing -- An array of route definitions. Each route matches HTTP requests by method and URL pattern and links them to a named connection.
connections -- A map where each key is a connection ID and each value defines the authentication type and its properties.

Route Configuration

Each entry under connection-routing defines a route:

Property	Required	Description

Property	Required	Description
`connection-id`	Yes	The key that links this route to an entry in the `connections` map.
`methods`	Yes	HTTP methods to match. Use `ALL` to match any method, or a comma-separated list: `GET`, `POST`, `PUT`, `DELETE`, `HEAD`, `OPTIONS`, `PATCH`.
`root-uris`	Yes	A list of URL patterns to match. Supports Ant-style patterns (see below).
`excluded-uris`	No	A list of URL patterns to exclude from matching, even if they match `root-uris`.

URL Pattern Matching

URL patterns use Spring's Ant-style path matching:

Pattern	Matches

Pattern	Matches
`<https://api.example.com/**`>	Any path under `<https://api.example.com/`>
`<https://api.example.com/v1/*`>	One path segment under `/v1/`
`<https://api.example.com/v1/**/users`>	Any intermediate segments between `/v1/` and `/users`

Route Example

connection-routing:
  - connection-id: my-api
    methods: GET, POST
    root-uris:
      - https://api.example.com/v1/**
      - https://api.example.com/v2/**
    excluded-uris:
      - https://api.example.com/v1/public/**

Connection Types

Each entry in the connections map must include connection-type to specify the authentication mechanism. The supported types are:

OAUTH20 -- OAuth 2.0 Authorization Code flow (user-delegated)
OAUTH20_CLIENT_CREDENTIALS -- OAuth 2.0 Client Credentials flow (machine-to-machine)
OAUTH10A -- OAuth 1.0a (e.g., IBM ELM)
FIXED_HEADERS -- Static headers (API keys, Basic Auth)
BEARER_TOKEN_FORWARD -- Forward the incoming request's bearer token

OAUTH20

User-delegated OAuth 2.0 using the Authorization Code flow. The library handles the full OAuth dance: redirecting the user for authorization, exchanging the code for tokens, and refreshing expired tokens.

Property	Required	Description

Property	Required	Description
`connection-type`	Yes	Must be `OAUTH20`
`client-id`	Yes	OAuth 2.0 client ID
`client-secret`	Yes	OAuth 2.0 client secret
`authorization-uri`	Yes	Authorization endpoint URL
`token-uri`	Yes	Token endpoint URL
`user-info-uri`	Yes	User info endpoint URL
`scopes`	No	Comma-separated list of OAuth scopes

connections:
  my-oauth2:
    connection-type: OAUTH20
    client-id: ${MY_CLIENT_ID}
    client-secret: ${MY_CLIENT_SECRET}
    authorization-uri: https://auth.example.com/authorize
    token-uri: https://auth.example.com/token
    user-info-uri: https://auth.example.com/userinfo
    scopes: openid, profile, email

When a token is not yet available, the library responds with HTTP 461 and an X-Authenticate-Via header containing the authorization URL. Clients should redirect the user to this URL to initiate authentication.

OAUTH20_CLIENT_CREDENTIALS

Machine-to-machine OAuth 2.0 using the Client Credentials flow. No user interaction is required.

Property	Required	Description

Property	Required	Description
`connection-type`	Yes	Must be `OAUTH20_CLIENT_CREDENTIALS`
`client-id`	Yes	OAuth 2.0 client ID
`client-secret`	Yes	OAuth 2.0 client secret
`token-uri`	Yes	Token endpoint URL
`scopes`	No	Comma-separated list of OAuth scopes

connections:
  machine-api:
    connection-type: OAUTH20_CLIENT_CREDENTIALS
    client-id: ${SERVICE_CLIENT_ID}
    client-secret: ${SERVICE_CLIENT_SECRET}
    token-uri: https://auth.example.com/token

OAUTH10A

OAuth 1.0a authentication, primarily used for IBM Engineering Lifecycle Management (ELM) integrations.

Property	Required	Description

Property	Required	Description
`connection-type`	Yes	Must be `OAUTH10A`
`consumer-key`	Yes	OAuth 1.0a consumer key
`consumer-secret`	Yes	OAuth 1.0a consumer secret
`root-services`	Yes	Root services discovery URL
`service-principal-enabled`	No	Enable the service principal flow (`true`/`false`, default: `false`)

connections:
  elm-server:
    connection-type: OAUTH10A
    consumer-key: ${ELM_CONSUMER_KEY}
    consumer-secret: ${ELM_CONSUMER_SECRET}
    root-services: https://elm.example.com/rootservices
    service-principal-enabled: false

FIXED_HEADERS

Injects static headers into every matched request. Useful for API keys, Basic Authentication, or any fixed credential.

Property	Required	Description

Property	Required	Description
`connection-type`	Yes	Must be `FIXED_HEADERS`
`headers`	Yes	A map of header name-value pairs

connections:
  my-api-key:
    connection-type: FIXED_HEADERS
    headers:
      X-API-Key: ${API_KEY}
      X-Custom-Header: some-value

For Basic Authentication:

connections:
  basic-auth-api:
    connection-type: FIXED_HEADERS
    headers:
      Authorization: Basic ${BASIC_AUTH_CREDENTIALS}

BEARER_TOKEN_FORWARD

Forwards the bearer token from the incoming HTTP request to the outbound request. No additional configuration properties are needed beyond the connection type.

Property	Required	Description

Property	Required	Description
`connection-type`	Yes	Must be `BEARER_TOKEN_FORWARD`

connections:
  downstream-service:
    connection-type: BEARER_TOKEN_FORWARD

Environment Variable Substitution

All values in connection-routing.yml support environment variable substitution using ${VAR} syntax:

Syntax	Behavior

Syntax	Behavior
`${VAR}`	Replaced with the value of environment variable `VAR`. Throws an error at startup if `VAR` is not set.
`${VAR:default}`	Replaced with the value of `VAR`, or `default` if `VAR` is not set.

Examples:

connections:
  my-api:
    connection-type: OAUTH20_CLIENT_CREDENTIALS
    client-id: ${OAUTH_CLIENT_ID}
    client-secret: ${OAUTH_CLIENT_SECRET}
    token-uri: ${OAUTH_TOKEN_URI:https://auth.example.com/token}

Environment variable substitution is applied during YAML parsing to connection properties including credentials, URIs, headers, and scopes.

Complete Example

Below is a full connection-routing.yml demonstrating all authentication types:

# connection-routing.yml

connection-routing:
  # OAuth 2.0 Authorization Code -- user-delegated access
  - connection-id: corporate-api
    methods: ALL
    root-uris:
      - https://api.corporate.example.com/**

  # OAuth 2.0 Client Credentials -- machine-to-machine
  - connection-id: data-service
    methods: GET, POST
    root-uris:
      - https://data.example.com/v1/**
    excluded-uris:
      - https://data.example.com/v1/health

  # OAuth 1.0a -- IBM ELM integration
  - connection-id: elm-server
    methods: ALL
    root-uris:
      - https://elm.example.com/**

  # Fixed headers -- API key authentication
  - connection-id: weather-api
    methods: GET
    root-uris:
      - https://api.weather.example.com/**

  # Bearer token forward -- pass-through to downstream service
  - connection-id: downstream
    methods: ALL
    root-uris:
      - https://internal.example.com/api/**

connections:
  corporate-api:
    connection-type: OAUTH20
    client-id: ${CORPORATE_CLIENT_ID}
    client-secret: ${CORPORATE_CLIENT_SECRET}
    authorization-uri: https://login.corporate.example.com/authorize
    token-uri: https://login.corporate.example.com/token
    user-info-uri: https://login.corporate.example.com/userinfo
    scopes: openid, profile, email

  data-service:
    connection-type: OAUTH20_CLIENT_CREDENTIALS
    client-id: ${DATA_SVC_CLIENT_ID}
    client-secret: ${DATA_SVC_CLIENT_SECRET}
    token-uri: https://auth.example.com/oauth/token

  elm-server:
    connection-type: OAUTH10A
    consumer-key: ${ELM_CONSUMER_KEY}
    consumer-secret: ${ELM_CONSUMER_SECRET}
    root-services: https://elm.example.com/rootservices
    service-principal-enabled: false

  weather-api:
    connection-type: FIXED_HEADERS
    headers:
      X-API-Key: ${WEATHER_API_KEY}

  downstream:
    connection-type: BEARER_TOKEN_FORWARD

Connection Routing Configuration