> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.2/admin-management/settings/workflow-forward-headers.md).

# 워크플로우 전파 헤더

## 개요

사용자 요청에 실려 온 HTTP 헤더 중 **일부를 워크플로우 실행 경로 끝(도구 호출)까지 전달**하는 기능입니다. 기존에는 어떤 헤더를 전달할지가 서비스별 소스코드에 흩어져 하드코딩돼 있어, 신규 커스텀 헤더(예: 고객사 연동용 `X-SRN-ID` 등)를 추가하려면 매번 코드 수정·배포가 필요했습니다.

이 기능은 전달 대상 헤더를 **GenOS configmap 한 곳(`WORKFLOW_FORWARD_HEADERS` / `WORKFLOW_FORWARD_HEADERS_DENY`)에서 통일 관리**하도록 바꿉니다. 이제 신규 헤더는 **코드 변경 없이 configmap에 이름만 추가**하면 전파됩니다. 관리자·운영 담당이 대상 클러스터의 configmap을 편집해 사용합니다.

## 주요 개념

| 개념                                         | 설명                                                                                                  |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| 전파 헤더(forward header)                      | 사용자 요청 헤더 중 워크플로우/도구 호출까지 실어 보내는 헤더                                                                 |
| allowlist (`WORKFLOW_FORWARD_HEADERS`)     | 전파할 헤더 이름 목록. 콤마 구분·대소문자 무시                                                                         |
| denylist (`WORKFLOW_FORWARD_HEADERS_DENY`) | allowlist 통과분 중 **제외**할 헤더 목록. allow 이후 적용                                                          |
| 와일드카드                                      | `*` = 전량 매칭 / `prefix-*` = 접두사 매칭 (예: `x-genos-*`)                                                  |
| subject 키                                  | 게이트웨이 라우팅·세션에 항상 필요한 기본 식별 헤더(`x-genos-user-id`·`-group-id`·`-auth-key-id`·`-session-id`). 기본 전파 대상 |
| 재방출(re-emit)                               | flowise가 워크플로우 vars에서 헤더를 꺼내 도구/서빙 호출 헤더로 다시 실어 보내는 단계                                              |

## 전파 체인

전파 헤더는 진입 서비스부터 도구 호출까지 5개 지점을 거칩니다. 각 구간이 동일한 allow/deny 규약을 공유합니다.

```
[사용자 요청 헤더]
   │  ① 진입: genportal-api(채팅) / chat-api  ── 요청 헤더에서 전파 대상 선별
   ▼
[gateway-api] ── ② WorkflowClient: subject 키 + 전파 헤더를 워크플로우 요청에 병합
   ▼
[workflow pod] ── ③ run_util_v2: overrideConfig.vars 에 헤더 주입 + 재방출 키 목록 기록
   ▼
[flowise] ── ④ getGenosSubjectHeaders: subject 키 ∪ 재방출 키 목록만 도구/서빙 호출 헤더로 재방출
   ▼
[도구 호출(GenosMCP 등)] ── ⑤ 최종적으로 헤더 수신
```

* **관리자 화면 "워크플로우 테스트"**(admin-front) 경로도 동일하게 전파됩니다(admin-api `deploy_test`). 실서비스와 같은 헤더가 도구까지 흐르므로 테스트 시 실동작을 그대로 확인할 수 있습니다.
* **`*` 와일드카드로 수집**하더라도, 도구로 **재방출되는 것은 실제 매칭된 concrete 헤더 목록뿐**입니다(워크플로우 내부 vars 전량을 훑지 않음). → 내부 설정값 유출 방지(§보안 고려사항).

## 설정 방법

전달 대상은 두 개의 configmap에 **같은 값으로** 둡니다(서비스별로 읽는 configmap이 다르기 때문).

| configmap                             | 읽는 서비스                                             |
| ------------------------------------- | -------------------------------------------------- |
| `llmops-global-configmap`             | genportal-api · chat-api · gateway-api · admin-api |
| `llmops-container-services-configmap` | workflow pod (run\_util\_v2)                       |

경로: `k8s-manifests/llmops/llmops-configmaps/`. 각 configmap `data`에 아래 두 키를 둡니다.

```yaml
# WORKFLOW_FORWARD_HEADERS      : 전파할 헤더 allowlist (콤마 구분, 대소문자 무시)
# WORKFLOW_FORWARD_HEADERS_DENY : allow 이후 제외할 denylist (콤마 구분)
WORKFLOW_FORWARD_HEADERS: "x-genos-user-id,x-genos-group-id,x-genos-auth-key-id,x-genos-session-id"
WORKFLOW_FORWARD_HEADERS_DENY: ""
```

### 매칭 규칙

* **콤마 구분**, 앞뒤 공백은 무시. 빈 항목은 건너뜀.
* **대소문자 무시** — 설정값·요청 헤더 모두 소문자로 정규화해 비교하고, 전달 키도 소문자로 나갑니다(`X-SRN-ID` → `x-srn-id`).
* **와일드카드**: `*`(전량) · `prefix-*`(접두사, 예 `x-genos-*`) · 그 외는 정확히 일치.
* **deny는 allow 다음**에 적용 — allow에 걸린 헤더라도 deny에 걸리면 제외됩니다.
* 값이 비어 있는(`""`·없음) 요청 헤더는 전달하지 않습니다.

### 신규 커스텀 헤더 추가 (예: 고객사 연동)

전달할 헤더 이름을 **allowlist 끝에 추가**하기만 하면 됩니다. 소스 수정 불필요.

```yaml
WORKFLOW_FORWARD_HEADERS: "x-genos-user-id,x-genos-group-id,x-genos-auth-key-id,x-genos-session-id,x-srn-id,x-inc-indv,x-trace-id,x-env-cd"
WORKFLOW_FORWARD_HEADERS_DENY: "x-cert-key"
```

위 예시는 subject 키에 더해 `x-srn-id`·`x-inc-indv`·`x-trace-id`·`x-env-cd`를 전파하고, 민감한 `x-cert-key`는 제외합니다.

### 설정 반영

configmap 값은 **파드 기동 시 환경변수로 로드**됩니다. 변경 후에는 해당 서비스 파드를 **롤아웃(재시작)** 해야 반영됩니다(global → genportal/chat/gateway/admin, container-services → workflow).

## 기본값과 동작

* 기본값은 **subject 키 4종**이며, deny는 비어 있습니다. 이는 기존에도 항상 전파되던 집합이라 **동작이 develop과 동일**합니다(기능 도입만으로 전파 범위가 늘지 않음).
* 커스텀 헤더를 흘리려면 운영 담당이 위 예시처럼 allowlist에 이름을 추가합니다.
* allowlist가 비어 있으면(`""`) 이 메커니즘으로는 아무 헤더도 전파하지 않습니다(게이트웨이가 기본으로 싣는 subject 키 전파는 별개로 유지).

## 보안 고려사항

* **내부 vars 유출 방지**: flowise는 워크플로우 vars 전체를 훑지 않고, run\_util\_v2가 넘긴 **concrete 재방출 키 목록(subject 키 + allow 매칭 헤더)만** 도구 호출에 재방출합니다. DB 접속정보·`security_level` 등 프레임워크 내부 vars는 목록에 없어 재방출되지 않습니다.
* **재방출 목록은 클라이언트가 조작 불가**: 요청자가 `x-genos-forward-header-keys` 같은 메타 헤더를 직접 보내도, run\_util\_v2가 allowlist 기준으로 재계산해 덮어씁니다.
* **토큰 노출 방지(기본값)**: 명시 allowlist를 쓰는 한 `x-genos-access-token`·`Authorization` 등 토큰은 전파/재방출 대상이 아닙니다. 재방출된 헤더는 도구/서빙 **요청 헤더**로만 나가며 사용자 응답 본문에는 실리지 않습니다.
* **`*` 와일드카드 사용 시 주의**: 임의 헤더가 vars로 유입·재방출될 수 있으므로,
  * 민감 헤더·토큰은 **반드시 deny에 추가**(`x-genos-access-token`, `authorization`, `x-genos-headers-*` 등),
  * 내부 vars 이름(`security_level`·`host`·`password`·`database` 등)과 **충돌하는 헤더명은 allowlist에 넣지 않도록** 합니다.

## 운영 시나리오

### 고객사 커스텀 헤더를 도구까지 전달한다

1. 두 configmap의 `WORKFLOW_FORWARD_HEADERS`에 헤더 이름을 추가(예: `...,x-srn-id,x-env-cd`).
2. global·container-services configmap 값을 **동일하게** 맞춘다.
3. genportal/chat/gateway/admin, workflow 파드를 롤아웃.
4. 검증: 대상 헤더를 실어 채팅(또는 "워크플로우 테스트")을 실행 → 도구 호출 아웃바운드 헤더에 해당 값이 찍히는지 확인(헤더 에코 도구/로그).

### 특정 민감 헤더만 제외한다

allowlist는 그대로 두고 `WORKFLOW_FORWARD_HEADERS_DENY`에 제외할 헤더명을 추가(예: `x-cert-key`). 롤아웃 후 해당 헤더만 도구 호출에서 빠진다.

### 전파가 안 될 때 점검 순서

1. **두 configmap** 값이 일치하는가(특히 workflow용 container-services 누락).
2. 파드가 **롤아웃**됐는가(설정은 기동 시 로드).
3. 헤더 이름 **오타/대소문자** — 내부적으로 소문자 정규화되므로 철자만 맞으면 됨.
4. deny에 걸려 있지 않은가.
5. 클라이언트가 실제로 그 헤더를 **보내고 있는가**(빈 값이면 전파 안 됨).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://genos-docs.gitbook.io/default/v1.9.2/admin-management/settings/workflow-forward-headers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.