From 8381389df905a8674d468c16a83f203493dc8ebc Mon Sep 17 00:00:00 2001 From: jinidev Date: Wed, 15 Apr 2026 14:46:13 +0300 Subject: [PATCH 1/5] Document for testing UAS api locally --- docs/Testing-UAS-Endpoints-Locally.mdx | 216 +++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 docs/Testing-UAS-Endpoints-Locally.mdx diff --git a/docs/Testing-UAS-Endpoints-Locally.mdx b/docs/Testing-UAS-Endpoints-Locally.mdx new file mode 100644 index 00000000000..817f748d9bd --- /dev/null +++ b/docs/Testing-UAS-Endpoints-Locally.mdx @@ -0,0 +1,216 @@ +# Testing UAS Endpoints Locally + +This guide provides instructions for developers to test User Activity Service (UAS) endpoints locally on their development environment. + +## Overview + +Testing UAS endpoints locally requires several setup steps to handle authentication, CORS issues, and session management. +This document outlines all necessary configurations. + +## Prerequisites + +- Local development environment running on `http://localhost:7081` +- Access to test or production BBC accounts +- A testing browser with extension support + +## Step 1: Install Browser Extension for CORS Testing + +To bypass CORS restrictions during local testing, you need to install a browser extension that allows you to modify HTTP headers. + +### Recommended Extension: ModHeader + +1. Install **ModHeader** extension for your browser: + +2. Configure ModHeader to set the `Access-Control-Allow-Origin` header: + - Open ModHeader extension settings + - Add a new request header: + - **Header Name**: `Access-Control-Allow-Origin` + - **Header Value**: `http://localhost:7081` + - Enable the extension for your local testing + +### Alternative Extensions + +You can use any browser extension that allows request/response header modification, such as: + +- CORS Unblock +- Allow CORS +- Requestly + +## Step 2: Disable Token Refresh to Avoid Session Endpoint CORS Issues + +The `refreshTokensIfExpired()` function in the UAS API layer makes calls to session endpoints that may encounter CORS issues in local testing. + +### File: `src/app/lib/uasApi/index.ts` + +**Action**: Comment out this line +// await refreshTokensIfExpired(); + +``` + +This prevents unnecessary token refresh calls during local development and testing. +Make sure to re-enable this before committing to ensure production token management works correctly. + +``` + +## Step 3: Obtain and Store Authentication Token + +The UAS API requires the `ckns_atkn` cookie for authentication via the Bearer token in the Authorization header. + +### How to Get the Token + +1. **Open the target BBC service** in your browser: + - Visit `https://test.bbc.com` or `https://bbc.com` + - Log in with your BBC account + +2. **Extract the cookie**: + - Open Developer Tools (F12 or Cmd+Option+I) + - Go to the **Application** or **Storage** tab + - Navigate to **Cookies** + - Copy the entire value + +3. **Store the cookie locally**: + - In your local development environment (`http://localhost:7081`), open Developer Tools + - Go to the **Application** or **Storage** tab + - Navigate to **Cookies** + - Create a new cookie: + - **Name**: `ckns_atkn` + - **Value**: Paste the value you copied from test.bbc.com or bbc.com + - **Domain**: `localhost` (will auto generate) + - **Path**: `/` + - **Expires**: Set to a future date or leave as Session + - Save the cookie + +### Token Expiration + +Tokens have a limited lifespan. If your tests fail with authentication errors, follow the steps above again to refresh the `ckns_atkn` cookie. + +## Step 4: Understand Current Authentication Implementation + +### Important: Cookie-Based Authentication in Production + +The current production implementation uses **cookie-based authentication** via the `credentials: 'include'` option in fetch requests. +This automatically includes all cookies (including `ckns_atkn`) in requests to the UAS API. + +**Current fetch configuration in `src/app/lib/uasApi/index.ts`**: + +```typescript +const response = await fetch(url, { + method, + headers, + credentials: 'include', // ← Automatically includes cookies like ckns_atkn + body: method === 'POST' ? JSON.stringify(body) : undefined, + ...(signal ? { signal } : {}), +}); +``` + +The `credentials: 'include'` setting means the browser automatically sends the `ckns_atkn` cookie with each request without explicit header manipulation. + +### Local Development Workaround: Authorization Bearer Header + +Modify the `getAuthHeaders` function with `Authorization: Bearer ${cknsAtkn}` header. +**This is a local development and testing workaround only** and is NOT used in production. + +### File: `src/app/lib/uasApi/getAuthHeaders.ts` + +**Proposed way for local development**: + +```typescript +import Cookie from 'js-cookie'; +import { getEnvConfig } from '../utilities/getEnvConfig'; + +const getAuthHeaders = (): HeadersInit => { + const apiKey = getEnvConfig().SIMORGH_UAS_PUBLIC_API_KEY; + + if (!apiKey) { + throw new Error('Missing UAS public API key'); + } + const cknsAtkn = Cookie.get('ckns_atkn') || ''; + const headers: HeadersInit = { + Authorization: `Bearer ${cknsAtkn}`, + 'X-API-Key': apiKey, + 'X-Authentication-Provider': 'idv5', + }; + + return headers; +}; + +export default getAuthHeaders; +``` + +**Key Lines to Review**: + +- **Line 1**: Imports `js-cookie` library for cookie access +- **Line 10**: Extracts `ckns_atkn` from cookies with empty string fallback +- **Line 12 and 14**: Sets the Authorization Bearer header with the token and 'X-Authentication-Provider' **(LOCAL TESTING ONLY)** +- **Line 14**: Sets the X-API-Key header for API authentication + +### Why This Workaround Exists + +During local development: + +- The browser's automatic cookie-sending mechanism (`credentials: 'include'`) may not work as expected due to localhost restrictions and CORS configurations +- The `Authorization: Bearer ${cknsAtkn}` header provides an explicit way to pass the authentication token +- This allows developers to test UAS endpoints locally without waiting for full CORS configuration resolution + +## Testing Checklist + +- [ ] ModHeader (or similar extension) installed and configured with `Access-Control-Allow-Origin: http://localhost:7081` +- [ ] Line 63 in `src/app/lib/uasApi/index.ts` is commented out +- [ ] `ckns_atkn` cookie is stored in browser local storage for `localhost` +- [ ] `getAuthHeaders` function is modified +- [ ] Development server is running on `http://localhost:7081` +- [ ] Browser is using the configured profile with the extension enabled + +## Troubleshooting + +### CORS Errors + +**Issue**: `Access to fetch at 'https://activity.api.bbc.com' has been blocked by CORS policy` + +**Solution**: + +- Ensure ModHeader extension is installed and enabled +- Verify that the `Access-Control-Allow-Origin` header is set to `http://localhost:7081` +- Check that the extension is configured for all sites + +### Authentication Errors (401/403) + +**Issue**: `UAS request failed with status 401` + +**Solution**: + +- Verify the `ckns_atkn` cookie is present in browser storage +- Copy a fresh token from test.bbc.com or bbc.com +- Check that the token hasn't expired +- Ensure the cookie domain is set correctly (should be `localhost` or left unspecified) + +### Token Expired + +**Issue**: Requests work initially but fail after some time + +**Solution**: + +- Tokens have limited lifespan (typically a few hours) +- Refresh the token by following Step 3 again +- Consider enabling `refreshTokensIfExpired()` in production once CORS issues are resolved + +## Notes for Developers + +- **Local Testing Only**: The `Authorization: Bearer ${cknsAtkn}` header workaround in `getAuthHeaders` is intended for local development only +- **Production Authentication**: Production uses `credentials: 'include'` in fetch requests to automatically send cookies - NOT the explicit Authorization header +- **Security**: Never commit changes that add Authorization headers for production use; this is a local-testing-only pattern +- **Token Safety**: Handle authentication tokens carefully; never share them or commit them to version control +- **Service Awareness**: Remember that UAS endpoint behavior may vary across different BBC services +- **Production Readiness**: Before deploying, ensure: + - No explicit `Authorization: Bearer` headers are added for production + - Remove 'X-Authentication-Provider' from getAUthHeaders + - `refreshTokensIfExpired()` is enabled in index.ts + - Authentication relies on `credentials: 'include'` and automatic cookie handling + - All authentication enhancements are properly tested + - No development-only modifications remain in the code + +## Additional Resources + +- [UAS Spike Documentation](#) (ihttps://www.dropbox.com/scl/fi/94qiwdrnobq3epmu4m880/UAS-Spike.paper?rlkey=6jqwue2tvb8j49xfy58ejq01b&dl=0) +- [UAS spec documentation](#) (https://confluence.dev.bbc.co.uk/spaces/AudienceDataPlatform/pages/269311433/UAS+User+Activity+Service) +- [CORS Overview](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) From 4fc086b9b90ee3759ef2e7775a0d7b3d54848e26 Mon Sep 17 00:00:00 2001 From: jinidev Date: Wed, 15 Apr 2026 14:56:47 +0300 Subject: [PATCH 2/5] Changes --- docs/Testing-UAS-Endpoints-Locally.mdx | 39 ++++++++++++-------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/docs/Testing-UAS-Endpoints-Locally.mdx b/docs/Testing-UAS-Endpoints-Locally.mdx index 817f748d9bd..6e8b6fa1dba 100644 --- a/docs/Testing-UAS-Endpoints-Locally.mdx +++ b/docs/Testing-UAS-Endpoints-Locally.mdx @@ -43,9 +43,9 @@ The `refreshTokensIfExpired()` function in the UAS API layer makes calls to sess ### File: `src/app/lib/uasApi/index.ts` **Action**: Comment out this line -// await refreshTokensIfExpired(); ``` +// await refreshTokensIfExpired(); This prevents unnecessary token refresh calls during local development and testing. Make sure to re-enable this before committing to ensure production token management works correctly. @@ -103,11 +103,9 @@ const response = await fetch(url, { }); ``` -The `credentials: 'include'` setting means the browser automatically sends the `ckns_atkn` cookie with each request without explicit header manipulation. - ### Local Development Workaround: Authorization Bearer Header -Modify the `getAuthHeaders` function with `Authorization: Bearer ${cknsAtkn}` header. +Modify the `getAuthHeaders` function with `Authorization: Bearer ${cknsAtkn}` and add `'X-Authentication-Provider': 'idv5 '`in headers. **This is a local development and testing workaround only** and is NOT used in production. ### File: `src/app/lib/uasApi/getAuthHeaders.ts` @@ -161,6 +159,21 @@ During local development: - [ ] Development server is running on `http://localhost:7081` - [ ] Browser is using the configured profile with the extension enabled +## Notes for Developers + +- **Local Testing Only**: The `Authorization: Bearer ${cknsAtkn}` header workaround in `getAuthHeaders` is intended for local development only +- **Production Authentication**: Production uses `credentials: 'include'` in fetch requests to automatically send cookies - NOT the explicit Authorization header +- **Security**: Never commit changes that add Authorization headers for production use; this is a local-testing-only pattern +- **Token Safety**: Handle authentication tokens carefully; never share them or commit them to version control +- **Service Awareness**: Remember that UAS endpoint behavior may vary across different BBC services +- **Production Readiness**: Before deploying, ensure: + - No explicit `Authorization: Bearer` headers are added for production + - Remove 'X-Authentication-Provider' from getAUthHeaders + - `refreshTokensIfExpired()` is enabled in index.ts + - Authentication relies on `credentials: 'include'` and automatic cookie handling + - All authentication enhancements are properly tested + - No development-only modifications remain in the code + ## Troubleshooting ### CORS Errors @@ -173,7 +186,7 @@ During local development: - Verify that the `Access-Control-Allow-Origin` header is set to `http://localhost:7081` - Check that the extension is configured for all sites -### Authentication Errors (401/403) +### Authentication Errors (401) **Issue**: `UAS request failed with status 401` @@ -192,22 +205,6 @@ During local development: - Tokens have limited lifespan (typically a few hours) - Refresh the token by following Step 3 again -- Consider enabling `refreshTokensIfExpired()` in production once CORS issues are resolved - -## Notes for Developers - -- **Local Testing Only**: The `Authorization: Bearer ${cknsAtkn}` header workaround in `getAuthHeaders` is intended for local development only -- **Production Authentication**: Production uses `credentials: 'include'` in fetch requests to automatically send cookies - NOT the explicit Authorization header -- **Security**: Never commit changes that add Authorization headers for production use; this is a local-testing-only pattern -- **Token Safety**: Handle authentication tokens carefully; never share them or commit them to version control -- **Service Awareness**: Remember that UAS endpoint behavior may vary across different BBC services -- **Production Readiness**: Before deploying, ensure: - - No explicit `Authorization: Bearer` headers are added for production - - Remove 'X-Authentication-Provider' from getAUthHeaders - - `refreshTokensIfExpired()` is enabled in index.ts - - Authentication relies on `credentials: 'include'` and automatic cookie handling - - All authentication enhancements are properly tested - - No development-only modifications remain in the code ## Additional Resources From c916b062b2825bd9b546fc04c27e387a8deb7f32 Mon Sep 17 00:00:00 2001 From: jinidev Date: Wed, 15 Apr 2026 15:51:36 +0300 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/Testing-UAS-Endpoints-Locally.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/Testing-UAS-Endpoints-Locally.mdx b/docs/Testing-UAS-Endpoints-Locally.mdx index 6e8b6fa1dba..b8796631e7c 100644 --- a/docs/Testing-UAS-Endpoints-Locally.mdx +++ b/docs/Testing-UAS-Endpoints-Locally.mdx @@ -105,7 +105,7 @@ const response = await fetch(url, { ### Local Development Workaround: Authorization Bearer Header -Modify the `getAuthHeaders` function with `Authorization: Bearer ${cknsAtkn}` and add `'X-Authentication-Provider': 'idv5 '`in headers. +Modify the `getAuthHeaders` function with `Authorization: Bearer ${cknsAtkn}` and add `'X-Authentication-Provider': 'idv5'` in headers. **This is a local development and testing workaround only** and is NOT used in production. ### File: `src/app/lib/uasApi/getAuthHeaders.ts` @@ -153,8 +153,8 @@ During local development: ## Testing Checklist - [ ] ModHeader (or similar extension) installed and configured with `Access-Control-Allow-Origin: http://localhost:7081` -- [ ] Line 63 in `src/app/lib/uasApi/index.ts` is commented out -- [ ] `ckns_atkn` cookie is stored in browser local storage for `localhost` +- [ ] `await refreshTokensIfExpired();` in `src/app/lib/uasApi/index.ts` is commented out +- [ ] `ckns_atkn` cookie is present in the browser's cookie store for `localhost` - [ ] `getAuthHeaders` function is modified - [ ] Development server is running on `http://localhost:7081` - [ ] Browser is using the configured profile with the extension enabled @@ -168,7 +168,7 @@ During local development: - **Service Awareness**: Remember that UAS endpoint behavior may vary across different BBC services - **Production Readiness**: Before deploying, ensure: - No explicit `Authorization: Bearer` headers are added for production - - Remove 'X-Authentication-Provider' from getAUthHeaders + - Remove 'X-Authentication-Provider' from getAuthHeaders - `refreshTokensIfExpired()` is enabled in index.ts - Authentication relies on `credentials: 'include'` and automatic cookie handling - All authentication enhancements are properly tested @@ -208,6 +208,6 @@ During local development: ## Additional Resources -- [UAS Spike Documentation](#) (ihttps://www.dropbox.com/scl/fi/94qiwdrnobq3epmu4m880/UAS-Spike.paper?rlkey=6jqwue2tvb8j49xfy58ejq01b&dl=0) +- [UAS Spike Documentation](#) (https://www.dropbox.com/scl/fi/94qiwdrnobq3epmu4m880/UAS-Spike.paper?rlkey=6jqwue2tvb8j49xfy58ejq01b&dl=0) - [UAS spec documentation](#) (https://confluence.dev.bbc.co.uk/spaces/AudienceDataPlatform/pages/269311433/UAS+User+Activity+Service) - [CORS Overview](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) From 03e110fe443f745dccca68260d350cf27996b72e Mon Sep 17 00:00:00 2001 From: jinidev Date: Wed, 15 Apr 2026 15:54:00 +0300 Subject: [PATCH 4/5] Clean up chores --- docs/Testing-UAS-Endpoints-Locally.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/Testing-UAS-Endpoints-Locally.mdx b/docs/Testing-UAS-Endpoints-Locally.mdx index b8796631e7c..399d96f99b2 100644 --- a/docs/Testing-UAS-Endpoints-Locally.mdx +++ b/docs/Testing-UAS-Endpoints-Locally.mdx @@ -1,3 +1,7 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + # Testing UAS Endpoints Locally This guide provides instructions for developers to test User Activity Service (UAS) endpoints locally on their development environment. @@ -59,7 +63,7 @@ The UAS API requires the `ckns_atkn` cookie for authentication via the Bearer to ### How to Get the Token 1. **Open the target BBC service** in your browser: - - Visit `https://test.bbc.com` or `https://bbc.com` + - Visit `https://test.bbc.com` - Log in with your BBC account 2. **Extract the cookie**: @@ -74,7 +78,7 @@ The UAS API requires the `ckns_atkn` cookie for authentication via the Bearer to - Navigate to **Cookies** - Create a new cookie: - **Name**: `ckns_atkn` - - **Value**: Paste the value you copied from test.bbc.com or bbc.com + - **Value**: Paste the value you copied from test.bbc.com - **Domain**: `localhost` (will auto generate) - **Path**: `/` - **Expires**: Set to a future date or leave as Session @@ -193,7 +197,7 @@ During local development: **Solution**: - Verify the `ckns_atkn` cookie is present in browser storage -- Copy a fresh token from test.bbc.com or bbc.com +- Copy a fresh token from test.bbc.com - Check that the token hasn't expired - Ensure the cookie domain is set correctly (should be `localhost` or left unspecified) From cd69f2970b0a14c523573c69cb7e6940c0a08b90 Mon Sep 17 00:00:00 2001 From: jinidev Date: Thu, 16 Apr 2026 11:41:25 +0300 Subject: [PATCH 5/5] included ckns_id mention --- docs/Testing-UAS-Endpoints-Locally.mdx | 46 ++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/Testing-UAS-Endpoints-Locally.mdx b/docs/Testing-UAS-Endpoints-Locally.mdx index 399d96f99b2..1407a1da058 100644 --- a/docs/Testing-UAS-Endpoints-Locally.mdx +++ b/docs/Testing-UAS-Endpoints-Locally.mdx @@ -16,6 +16,13 @@ This document outlines all necessary configurations. - Local development environment running on `http://localhost:7081` - Access to test or production BBC accounts - A testing browser with extension support +- **Feature Toggle**: Ensure the `uasPersonalization` feature toggle is enabled in your environment configuration: + ```json + uasPersonalization: { + enabled: true + } + ``` + This enables the UAS personalization features required for testing ## Step 1: Install Browser Extension for CORS Testing @@ -88,6 +95,29 @@ The UAS API requires the `ckns_atkn` cookie for authentication via the Bearer to Tokens have a limited lifespan. If your tests fail with authentication errors, follow the steps above again to refresh the `ckns_atkn` cookie. +## Step 3.2: Verify User Sign-In Status with `ckns_id` Cookie + +### Why This Cookie Matters + +The `ckns_id` cookie is essential for UAS functionality. +**Without this cookie, the UAS button will not be visible** in your local testing environment, even if other setup is correct. +This cookie validates whether the user is signed in or not and is required for the UI to display UAS-related features. + +### How to Verify and Add the `ckns_id` Cookie + +1. **Extract the `ckns_id` cookie from test.bbc.com**: + +2. **Store the `ckns_id` cookie locally**: + +### Verifying Both Authentication Cookies + +After completing Steps 3 and 3.2, you should have **both** cookies in your local browser storage: + +- `ckns_atkn` - Authentication token for API requests +- `ckns_id` - User identification and sign-in status (required for UAS UI visibility) + +If the UAS button is still not visible, verify that both cookies are present and have valid values. + ## Step 4: Understand Current Authentication Implementation ### Important: Cookie-Based Authentication in Production @@ -159,9 +189,11 @@ During local development: - [ ] ModHeader (or similar extension) installed and configured with `Access-Control-Allow-Origin: http://localhost:7081` - [ ] `await refreshTokensIfExpired();` in `src/app/lib/uasApi/index.ts` is commented out - [ ] `ckns_atkn` cookie is present in the browser's cookie store for `localhost` +- [ ] `ckns_id` cookie is present in the browser's cookie store for `localhost` (required for UAS button visibility) - [ ] `getAuthHeaders` function is modified - [ ] Development server is running on `http://localhost:7081` - [ ] Browser is using the configured profile with the extension enabled +- [ ] UAS button is visible in the UI (indicates user is properly authenticated) ## Notes for Developers @@ -210,6 +242,20 @@ During local development: - Tokens have limited lifespan (typically a few hours) - Refresh the token by following Step 3 again +### UAS Button Not Visible + +**Issue**: The UAS feature button is not appearing in the UI despite other setup being complete + +**Solution**: + +- Ensure `uasPersonalization` toggle is ON in local config +- Verify that the `ckns_id` cookie is present in your browser's cookie store for `localhost` +- Copy a fresh `ckns_id` cookie from test.bbc.com following Step 3.5 +- Ensure both `ckns_atkn` and `ckns_id` cookies are present +- The `ckns_id` cookie validates user sign-in status; without it, the UI will not display UAS features +- Clear browser cache and reload the page after adding the cookies +- Check the browser console for any errors related to authentication or feature detection + ## Additional Resources - [UAS Spike Documentation](#) (https://www.dropbox.com/scl/fi/94qiwdrnobq3epmu4m880/UAS-Spike.paper?rlkey=6jqwue2tvb8j49xfy58ejq01b&dl=0)