From b5d10f9f797cdbdf13d9ff3b3ff59ec2c79db841 Mon Sep 17 00:00:00 2001 From: patelila Date: Tue, 24 Mar 2026 09:53:43 +0000 Subject: [PATCH 1/5] Add README notes for OIDC issuer and callback host settings --- README.md | 10 ++++++++++ compose/backend.yml | 6 ++++++ compose/case-document-am.yml | 1 + compose/case-payment-orders.yml | 1 + compose/ts-translation-service.yml | 1 + 5 files changed, 19 insertions(+) diff --git a/README.md b/README.md index 620bdb4..cf7abd0 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,12 @@ Ignore if we get error message ccd-network already exists while running above co > [!CAUTION] > Some users of zsh 'Oh My Zsh' experienced issues. > Try switching to bash by : `chsh -s /bin/bash` + + Important environment notes: + - `OIDC_ISSUER` must be derived from a real access token for the target environment. Do not guess it from the public OIDC discovery URL. + - `CCD_CALLBACK_ALLOWED_HOSTS` is the comma-separated allow-list of HTTPS callback target hosts CCD services may call. + - `CCD_CALLBACK_ALLOWED_HTTP_HOSTS` is the comma-separated allow-list of HTTP callback target hosts CCD services may call. + - `CCD_CALLBACK_ALLOW_PRIVATE_HOSTS` controls whether callbacks to private or local hostnames are allowed for local development. To persist the environment variables in Linux/Mac run the following script to add the script into your ~/.bash_profile. @@ -835,6 +841,10 @@ Here are the important variables exposed in the compose files: | USER_PROFILE_S2S_AUTHORISED_SERVICES | List of micro-services authorised to call this service, comma-separated, as registered in `service-auth-provider-api` | | DATA_STORE_TOKEN_SECRET | Secret for generation of internal event tokens | | APPINSIGHTS_INSTRUMENTATIONKEY | Secret for Microsoft Insights logging, can be a dummy string in local | +| OIDC_ISSUER | Enforced JWT issuer value used by services that validate IDAM access tokens. This must match the token `iss` claim for the target environment and should be derived from a real token, not guessed from the public discovery URL. | +| CCD_CALLBACK_ALLOWED_HOSTS | Comma-separated allow-list of callback target hosts that CCD services may call over HTTPS. Local defaults include `localhost`, `127.0.0.1`, and `host.docker.internal`. | +| CCD_CALLBACK_ALLOWED_HTTP_HOSTS | Comma-separated allow-list of callback target hosts that CCD services may call over HTTP. Use this only when local callback endpoints are intentionally served over plain HTTP. | +| CCD_CALLBACK_ALLOW_PRIVATE_HOSTS | Controls whether callback targets on private or local hostnames are allowed. This supports local development callbacks to host services outside the Docker network. | | STORAGEACCOUNT_PRIMARY_CONNECTION_STRING | (If dm-store is enabled) Secret for Azure Blob Storage. It is pointing to dockerized Azure Blob Storage emulator. | | STORAGE_CONTAINER_DOCUMENT_CONTAINER_NAME | (If dm-store is enabled) Container name for Azure Blob Storage | | AM_DB | Access Management database name | diff --git a/compose/backend.yml b/compose/backend.yml index 0f75630..3292a94 100644 --- a/compose/backend.yml +++ b/compose/backend.yml @@ -83,6 +83,7 @@ services: IDAM_USER_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" # For backward compatibility with older images IDAM_API_BASE_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" IDAM_OIDC_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" + OIDC_ISSUER: ${OIDC_ISSUER:-http://localhost:5000/o} IDAM_S2S_URL: "${IDAM_S2S_URL:-http://service-auth-provider-api:8080}" IDAM_OAUTH2_DATA_STORE_CLIENT_SECRET: idam_data_store_client_secret REFORM_SERVICE_NAME: ccd-data-store-api @@ -101,6 +102,11 @@ services: MIGRATIONS_ENDPOINT_ENABLED: "${MIGRATIONS_ENDPOINT_ENABLED:-true}" REFERENCE_DATA_API_URL: "${REFERENCE_DATA_API_URL:-http://ccd-test-stubs-service:5555}" ROLE_ASSIGNMENT_URL: "${ROLE_ASSIGNMENT_URL:-http://am-role-assignment-service:4096}" + TEST_STUB_SERVICE_BASE_URL: "http://host.docker.internal:5555" + BEFTA_TEST_STUB_SERVICE_BASE_URL: "http://localhost:5555" + CCD_CALLBACK_ALLOWED_HOSTS: "localhost,127.0.0.1,host.docker.internal" + CCD_CALLBACK_ALLOWED_HTTP_HOSTS: "localhost,127.0.0.1,host.docker.internal" + CCD_CALLBACK_ALLOW_PRIVATE_HOSTS: "localhost,127.0.0.1,host.docker.internal" ### other env vars can be added here as needed ############# # ENABLE_CASE_GROUP_ACCESS_FILTERING: "true" # DATA_STORE_TX_TIMEOUT_DEFAULT: 120 # in seconds diff --git a/compose/case-document-am.yml b/compose/case-document-am.yml index bb3dd27..1ef6634 100644 --- a/compose/case-document-am.yml +++ b/compose/case-document-am.yml @@ -8,6 +8,7 @@ services: CASE_DOCUMENT_S2S_AUTHORISED_SERVICES: ccd_case_document_am_api,ccd_gw,xui_webapp,ccd_data,bulk_scan_processor,bulk_scan_orchestrator IDAM_API_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" IDAM_OIDC_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" + OIDC_ISSUER: ${OIDC_ISSUER:-http://localhost:5000/o} S2S_URL: http://service-auth-provider-api:8080 DM_STORE_BASE_URL: http://dm-store:8080 CCD_DATA_STORE_API_BASE_URL: http://ccd-data-store-api:4452 diff --git a/compose/case-payment-orders.yml b/compose/case-payment-orders.yml index 42db9dc..8f109cf 100644 --- a/compose/case-payment-orders.yml +++ b/compose/case-payment-orders.yml @@ -12,6 +12,7 @@ services: CPO_S2S_AUTHORISED_SERVICES: xui_webapp,payment_app IDAM_API_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" IDAM_OIDC_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" + OIDC_ISSUER: ${OIDC_ISSUER:-http://localhost:5000/o} S2S_URL: http://service-auth-provider-api:8080 # override default 'xui_webapp' permissions with values that support the FTA tests S2S_AUTHORIZATIONS_XUI_ID: xui_webapp diff --git a/compose/ts-translation-service.yml b/compose/ts-translation-service.yml index 740eceb..e05968d 100644 --- a/compose/ts-translation-service.yml +++ b/compose/ts-translation-service.yml @@ -17,6 +17,7 @@ services: TS_TRANSLATION_SERVICE_DB_PASSWORD: ${DB_PASSWORD} IDAM_API_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" IDAM_OIDC_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" + OIDC_ISSUER: ${OIDC_ISSUER:-http://idam:5000/o} TS_TRANSLATION_SERVICE_S2S_AUTHORISED_SERVICES: xui_webapp,ccd_admin,ccd_definition S2S_URL: http://service-auth-provider-api:8080 REFORM_SERVICE_NAME: ts-translation-service From caa1123bfa7968c8475c501ed5c142433d12269d Mon Sep 17 00:00:00 2001 From: patelila Date: Tue, 24 Mar 2026 10:09:21 +0000 Subject: [PATCH 2/5] docs: clarify JWT issuer payload decode example --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index cf7abd0..44dda16 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,26 @@ Ignore if we get error message ccd-network already exists while running above co - `CCD_CALLBACK_ALLOWED_HOSTS` is the comma-separated allow-list of HTTPS callback target hosts CCD services may call. - `CCD_CALLBACK_ALLOWED_HTTP_HOSTS` is the comma-separated allow-list of HTTP callback target hosts CCD services may call. - `CCD_CALLBACK_ALLOW_PRIVATE_HOSTS` controls whether callbacks to private or local hostnames are allowed for local development. + + How to derive `OIDC_ISSUER`: + - Do not guess the issuer from the public discovery URL alone. + - Decode only the JWT payload from a real access token for the target environment and inspect the `iss` claim. + - Do not store or document full bearer tokens. Record only the derived issuer value. + + Example: + ```bash + TOKEN='eyJ...' + PAYLOAD=$(printf '%s' "$TOKEN" | cut -d '.' -f2) + python3 - <<'PY' "$PAYLOAD" + import base64, json, sys + payload = sys.argv[1] + payload += '=' * (-len(payload) % 4) + print(json.loads(base64.urlsafe_b64decode(payload))["iss"]) + PY + ``` + - JWTs are `header.payload.signature`. + - The second segment is base64url-encoded JSON. + - This decodes the payload only. It does not verify the signature. To persist the environment variables in Linux/Mac run the following script to add the script into your ~/.bash_profile. From 68b3976b94c8b11dfc4fb68d61cf98f82b2160ab Mon Sep 17 00:00:00 2001 From: patelila Date: Tue, 24 Mar 2026 12:05:33 +0000 Subject: [PATCH 3/5] Clarify OIDC issuer and callback settings in ccd-docker docs --- README.md | 15 +++++++++++++-- compose/backend.yml | 10 +++++++--- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 44dda16..ad68753 100644 --- a/README.md +++ b/README.md @@ -127,13 +127,13 @@ Ignore if we get error message ccd-network already exists while running above co > Some users of zsh 'Oh My Zsh' experienced issues. > Try switching to bash by : `chsh -s /bin/bash` - Important environment notes: + **Important environment notes:** - `OIDC_ISSUER` must be derived from a real access token for the target environment. Do not guess it from the public OIDC discovery URL. - `CCD_CALLBACK_ALLOWED_HOSTS` is the comma-separated allow-list of HTTPS callback target hosts CCD services may call. - `CCD_CALLBACK_ALLOWED_HTTP_HOSTS` is the comma-separated allow-list of HTTP callback target hosts CCD services may call. - `CCD_CALLBACK_ALLOW_PRIVATE_HOSTS` controls whether callbacks to private or local hostnames are allowed for local development. - How to derive `OIDC_ISSUER`: + **How to derive `OIDC_ISSUER`:** - Do not guess the issuer from the public discovery URL alone. - Decode only the JWT payload from a real access token for the target environment and inspect the `iss` claim. - Do not store or document full bearer tokens. Record only the derived issuer value. @@ -152,6 +152,17 @@ Ignore if we get error message ccd-network already exists while running above co - JWTs are `header.payload.signature`. - The second segment is base64url-encoded JSON. - This decodes the payload only. It does not verify the signature. + The following services in `ccd-docker` compose set both `IDAM_OIDC_URL` and `OIDC_ISSUER`: + + | Service | + | --- | + | `ccd-data-store-api` | + | `ccd-definition-store-api` | + | `cpo-case-payment-orders-api` | + | `ts-translation-service` | + | `ccd-case-document-am-api` | + + `VERIFY_OIDC_ISSUER=true` is not set in this repo's compose YAML. Use it only in service repos that include a live issuer verifier, where it enables a pre-check that fetches a real test token and fails fast if its `iss` claim does not exactly match `OIDC_ISSUER`. To persist the environment variables in Linux/Mac run the following script to add the script into your ~/.bash_profile. diff --git a/compose/backend.yml b/compose/backend.yml index 3292a94..31ceb40 100644 --- a/compose/backend.yml +++ b/compose/backend.yml @@ -27,6 +27,7 @@ services: ccd-definition-store-api: image: "${CCD_DEFINITION_STORE_API_USE_LOCAL-hmctspublic.azurecr.io/}ccd/definition-store-api:${CCD_DEFINITION_STORE_API_TAG:-latest}" + #image: hmcts/definition-store-api:local environment: DEFINITION_STORE_DB_HOST: ccd-shared-database DEFINITION_STORE_DB_PORT: 5432 @@ -37,6 +38,8 @@ services: DEFINITION_STORE_S2S_AUTHORISED_SERVICES: ccd_data,ccd_gw,ccd_admin,aac_manage_case_assignment,ccd_case_disposer USER_PROFILE_HOST: http://ccd-user-profile-api:4453 IDAM_USER_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" + IDAM_OIDC_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" + OIDC_ISSUER: ${OIDC_ISSUER:-http://localhost:5000/o} IDAM_S2S_URL: "${IDAM_S2S_URL:-http://service-auth-provider-api:8080}" REFORM_SERVICE_NAME: ccd-definition-store-api REFORM_TEAM: ccd @@ -55,7 +58,7 @@ services: ports: - 4451:4451 # Uncomment this and the JAVA_TOOL_OPTIONS flag for JVM debugging - # - 5005:5005 + # - 5006:5006 depends_on: idam-healthcheck: condition: service_healthy @@ -67,7 +70,8 @@ services: - ccd-network ccd-data-store-api: - image: "${CCD_DATA_STORE_API_USE_LOCAL-hmctspublic.azurecr.io/}ccd/data-store-api:${CCD_DATA_STORE_API_TAG:-latest}" + #image: "${CCD_DATA_STORE_API_USE_LOCAL-hmctspublic.azurecr.io/}ccd/data-store-api:${CCD_DATA_STORE_API_TAG:-latest}" + image: hmcts/data-store-api:local environment: CASE_DOCUMENT_AM_URL: http://ccd-case-document-am-api:4455 DATA_STORE_DB_HOST: ccd-shared-database @@ -165,7 +169,7 @@ services: ports: - 4096:4096 # Uncomment this and the JAVA_TOOL_OPTIONS flag for JVM debugging - # - 5005:5005 + # - 5008:5008 depends_on: idam-healthcheck: condition: service_healthy From e3a7d3e1dd6a98556be0a11eccf1433072cb3f5e Mon Sep 17 00:00:00 2001 From: patelila Date: Thu, 26 Mar 2026 10:43:11 +0000 Subject: [PATCH 4/5] Align compose JWT issuer defaults with in-network IDAM issuer --- compose/backend.yml | 4 ++-- compose/case-document-am.yml | 2 +- compose/case-payment-orders.yml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/compose/backend.yml b/compose/backend.yml index 31ceb40..7c5aaed 100644 --- a/compose/backend.yml +++ b/compose/backend.yml @@ -39,7 +39,7 @@ services: USER_PROFILE_HOST: http://ccd-user-profile-api:4453 IDAM_USER_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" IDAM_OIDC_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" - OIDC_ISSUER: ${OIDC_ISSUER:-http://localhost:5000/o} + OIDC_ISSUER: ${OIDC_ISSUER:-http://idam:5000/o} IDAM_S2S_URL: "${IDAM_S2S_URL:-http://service-auth-provider-api:8080}" REFORM_SERVICE_NAME: ccd-definition-store-api REFORM_TEAM: ccd @@ -87,7 +87,7 @@ services: IDAM_USER_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" # For backward compatibility with older images IDAM_API_BASE_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" IDAM_OIDC_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" - OIDC_ISSUER: ${OIDC_ISSUER:-http://localhost:5000/o} + OIDC_ISSUER: ${OIDC_ISSUER:-http://idam:5000/o} IDAM_S2S_URL: "${IDAM_S2S_URL:-http://service-auth-provider-api:8080}" IDAM_OAUTH2_DATA_STORE_CLIENT_SECRET: idam_data_store_client_secret REFORM_SERVICE_NAME: ccd-data-store-api diff --git a/compose/case-document-am.yml b/compose/case-document-am.yml index 1ef6634..fcc7eda 100644 --- a/compose/case-document-am.yml +++ b/compose/case-document-am.yml @@ -8,7 +8,7 @@ services: CASE_DOCUMENT_S2S_AUTHORISED_SERVICES: ccd_case_document_am_api,ccd_gw,xui_webapp,ccd_data,bulk_scan_processor,bulk_scan_orchestrator IDAM_API_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" IDAM_OIDC_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" - OIDC_ISSUER: ${OIDC_ISSUER:-http://localhost:5000/o} + OIDC_ISSUER: ${OIDC_ISSUER:-http://idam:5000/o} S2S_URL: http://service-auth-provider-api:8080 DM_STORE_BASE_URL: http://dm-store:8080 CCD_DATA_STORE_API_BASE_URL: http://ccd-data-store-api:4452 diff --git a/compose/case-payment-orders.yml b/compose/case-payment-orders.yml index 8f109cf..af0f002 100644 --- a/compose/case-payment-orders.yml +++ b/compose/case-payment-orders.yml @@ -12,7 +12,7 @@ services: CPO_S2S_AUTHORISED_SERVICES: xui_webapp,payment_app IDAM_API_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" IDAM_OIDC_URL: "${IDAM_INTERNAL_API_BASE_URL:-http://idam:5000}" - OIDC_ISSUER: ${OIDC_ISSUER:-http://localhost:5000/o} + OIDC_ISSUER: ${OIDC_ISSUER:-http://idam:5000/o} S2S_URL: http://service-auth-provider-api:8080 # override default 'xui_webapp' permissions with values that support the FTA tests S2S_AUTHORIZATIONS_XUI_ID: xui_webapp From 805cfde0f8ea375f7f55f858fab557e791ee9641 Mon Sep 17 00:00:00 2001 From: patelila Date: Thu, 26 Mar 2026 12:28:36 +0000 Subject: [PATCH 5/5] same as master without my local changes --- compose/backend.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/compose/backend.yml b/compose/backend.yml index 7c5aaed..3a43e81 100644 --- a/compose/backend.yml +++ b/compose/backend.yml @@ -27,7 +27,6 @@ services: ccd-definition-store-api: image: "${CCD_DEFINITION_STORE_API_USE_LOCAL-hmctspublic.azurecr.io/}ccd/definition-store-api:${CCD_DEFINITION_STORE_API_TAG:-latest}" - #image: hmcts/definition-store-api:local environment: DEFINITION_STORE_DB_HOST: ccd-shared-database DEFINITION_STORE_DB_PORT: 5432 @@ -58,7 +57,7 @@ services: ports: - 4451:4451 # Uncomment this and the JAVA_TOOL_OPTIONS flag for JVM debugging - # - 5006:5006 + # - 5005:5005 depends_on: idam-healthcheck: condition: service_healthy @@ -70,8 +69,7 @@ services: - ccd-network ccd-data-store-api: - #image: "${CCD_DATA_STORE_API_USE_LOCAL-hmctspublic.azurecr.io/}ccd/data-store-api:${CCD_DATA_STORE_API_TAG:-latest}" - image: hmcts/data-store-api:local + image: "${CCD_DATA_STORE_API_USE_LOCAL-hmctspublic.azurecr.io/}ccd/data-store-api:${CCD_DATA_STORE_API_TAG:-latest}" environment: CASE_DOCUMENT_AM_URL: http://ccd-case-document-am-api:4455 DATA_STORE_DB_HOST: ccd-shared-database @@ -169,7 +167,7 @@ services: ports: - 4096:4096 # Uncomment this and the JAVA_TOOL_OPTIONS flag for JVM debugging - # - 5008:5008 + # - 5005:5005 depends_on: idam-healthcheck: condition: service_healthy