From 8381389df905a8674d468c16a83f203493dc8ebc Mon Sep 17 00:00:00 2001 From: jinidev Date: Wed, 15 Apr 2026 14:46:13 +0300 Subject: [PATCH 1/6] 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/6] 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/6] 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/6] 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/6] 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) From aff0b78840698a72b6580b3459f42846d822afce Mon Sep 17 00:00:00 2001 From: jinidev Date: Fri, 17 Apr 2026 16:25:57 +0300 Subject: [PATCH 6/6] Link to simorrg-infrastruture --- docs/Testing-UAS-Endpoints-Locally.mdx | 257 +------------------------ 1 file changed, 2 insertions(+), 255 deletions(-) diff --git a/docs/Testing-UAS-Endpoints-Locally.mdx b/docs/Testing-UAS-Endpoints-Locally.mdx index 1407a1da058..3e61cc403ad 100644 --- a/docs/Testing-UAS-Endpoints-Locally.mdx +++ b/docs/Testing-UAS-Endpoints-Locally.mdx @@ -6,258 +6,5 @@ import { Meta } from '@storybook/addon-docs/blocks'; 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 -- **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 - -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` - - 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 - - **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 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 - -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 } : {}), -}); -``` - -### Local Development Workaround: Authorization Bearer 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` - -**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` -- [ ] `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 - -- **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 - -**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) - -**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 -- 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 - -### 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) -- [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) +For comprehensive infrastructure setup and configuration details, +refer to the [UAS Testing Documentation in the simorgh-infrastructure repository](https://github.com/bbc/simorgh-infrastructure/blob/create-doc-on-UAS-testing-locally/documentation/testing-simorgh-uas-endpoints-locally.md).