Cross-Origin Resource Sharing (CORS) begrijpen voor finesse

Inleiding

Dit document beschrijft Cross-Origin Resource Sharing volledig, zodat tijdens het oplossen van problemen de onderliggende processen grondig worden begrepen.

Voorwaarden

Vereisten

Cisco raadt kennis van de volgende onderwerpen aan:

• Cisco Unified Contact Center Enterprise (UCCE) versie 12.6.x
• Cisco Packaged Contact Center Enterprise (PCCE) versie 12.6.x
• Cisco Finesse release 12.6.x
• Cisco Unified Intelligence Center (CUIC) versie 12.6.x

Gebruikte componenten

De informatie in dit document is gebaseerd op de volgende software- en hardware-versies:

• UCCE-release 12.6.2
• Finesse release 12.6.2
• CUIC-release 12.6.2

De informatie in dit document is gebaseerd op de apparaten in een specifieke laboratoriumomgeving. Alle apparaten die in dit document worden beschreven, hadden een opgeschoonde (standaard)configuratie. Als uw netwerk live is, moet u zorgen dat u de potentiële impact van elke opdracht begrijpt.

Achtergrondinformatie

Wat is CORS

Cross-Origin Resource Sharing (CORS) is een manier voor servers om te bepalen welke websites (domeinen, protocollen en poorten) toegang hebben tot hun bronnen. Terwijl browsers normaal gesproken verzoeken van verschillende oorsprong blokkeren (hetzelfde oorsprongsbeleid), geeft CORS servers de mogelijkheid om deze beperking selectief te versoepelen. In wezen gebruiken servers speciale HTTP-headers om de browser te vertellen welke oorsprong is toegestaan, welke soorten verzoeken zijn toegestaan (zoals GET, POST, enzovoort) en welke aangepaste headers kunnen worden opgenomen. Hierdoor kunnen servers beslissen wie toegang heeft tot hun API's en hoe, variërend van volledig open tot strikt beperkte toegang. CORS werkt door de browser en server via deze HTTP-headers te laten communiceren om cross-origin-verzoeken te beheren.

CORS maakt gebruik van HTTP headers om gecontroleerde cross-origin verzoeken mogelijk te maken. De browser en server communiceren via deze headers, waarbij de server de toegestane oorsprong, methoden en headers opgeeft. Als de reactiekoppen van de server ontbreken of ongeldig zijn, blokkeert de browser de reactie en wordt hetzelfde oorsprongsbeleid toegepast. Voor bepaalde verzoeken stuurt de browser eerst een preflight-verzoek naar de server om ervoor te zorgen dat deze het daadwerkelijke cross-origin-verzoek accepteert.

Browsers gebruiken preflight-verzoeken om te controleren of een server een cross-origin-verzoek toestaat voordat het echte verzoek wordt verzonden. Deze preflight-verzoeken bevatten details zoals de HTTP-methode en aangepaste headers. CORS-enabled servers kunnen dan reageren, ofwel het toestaan of het weigeren van de werkelijke aanvraag. Als een server niet is geconfigureerd voor CORS, reageert deze niet correct op de preflight en blokkeert de browser het eigenlijke verzoek, waardoor de server wordt beschermd tegen ongewenste cross-origin toegang.

Cross-Origin Resource Sharing (CORS) is cruciaal voor webbeveiliging en -functionaliteit. Het maakt gecontroleerde toegang tot bronnen van verschillende oorsprong (domeinen, protocollen, poorten) mogelijk, wat nodig is omdat browsers een Same-Origin-beleid afdwingen dat dergelijke toegang normaal blokkeert.

Levenscyclus van een CORS

Een CORS-verzoek bestaat uit twee kanten: de client die het verzoek indient en de server die het verzoek ontvangt. Aan de clientzijde schrijft de ontwikkelaar JavaScript-code om het verzoek naar de server te sturen. De server reageert op het verzoek door speciale CORS-specifieke headers in te stellen om aan te geven dat het cross-origin verzoek is toegestaan. Zonder de deelname van zowel de client als de server mislukt het CORS-verzoek.

De belangrijkste spelers in een CORS-verzoek zijn de client, de browser en de server. De client wil bepaalde gegevens van de server, zoals een JSON API-reactie of de inhoud van een webpagina. De browser fungeert als de vertrouwde tussenpersoon om te controleren of de client toegang heeft tot de gegevens van de server.

Klant:

 De client is een fragment van JavaScript-code die op een website wordt uitgevoerd en is verantwoordelijk voor het initiëren van het CORS-verzoek

Opmerking: Finesse is een webtoepassing. Het wordt geïnstalleerd op een server en agenten krijgen er toegang toe door hun webbrowsers te gebruiken, waardoor de installatie aan de clientzijde of het onderhoud van plug-ins of andere software overbodig wordt. Zoals aangetoond in de CORS in Action met Cisco Finesse voorbeeld, ondersteunt deze architectuur functies zoals live data rapporten. In deze context fungeert de JavaScript-code van het Cisco Finesse live data-gadget als de client, terwijl Cisco CUIC fungeert als de server binnen de CORS-levenscyclus. In wezen werkt de browser-gebaseerde Finesse-client samen met de CUIC-server om live gegevens op te halen.

Klant versus gebruiker:

Soms worden de woorden client en gebruiker door elkaar gebruikt, maar ze zijn verschillend in de context van CORS. Een gebruiker is een persoon die een website bezoekt of een Finesse-gebruiker (agent of toezichthouder) die in deze context toegang heeft tot Finesse, terwijl een klant de daadwerkelijke code is die door die website wordt bediend. Meerdere gebruikers kunnen dezelfde website bezoeken en dezelfde JavaScript-clientcode krijgen.

Browser:

De browser, ook bekend als de user agent, host de code aan de clientzijde. Het speelt een cruciale rol in CORS door extra informatie toe te voegen aan uitgaande verzoeken, waardoor de server de client kan identificeren. Bovendien interpreteert de browser de reactie van de server, waarbij wordt bepaald of de gegevens aan de client moeten worden geleverd of een fout moeten worden geretourneerd. Deze acties aan de browserzijde zijn essentieel voor het handhaven van de veiligheid die wordt geboden door hetzelfde herkomstbeleid. Zonder de handhaving van de CORS-regels door de browser konden klanten ongeautoriseerde verzoeken indienen, waardoor dit vitale beveiligingsmechanisme in gevaar kwam.

Server:

De server is de bestemming van het CORS-verzoek en het is CUIC voor Live data-gadget, bijvoorbeeld met Cisco Finesse. De server slaat de gegevens op die de klant wil en heeft het laatste woord over de vraag of het CORS-verzoek is toegestaan of niet.

Nu u weet wie betrokken is bij een CORS-verzoek, laten we eens kijken naar hoe ze allemaal samenwerken. De volgende afbeeldingen illustreren de levenscyclus van CORS op hoog niveau:

1. De cliënt initieert het verzoek.

2. De browser voegt aanvullende informatie toe aan het verzoek en stuurt deze door naar de server.

3. De server beslist hoe hij op het verzoek reageert en stuurt het antwoord naar de browser.

4. De browser beslist of de client toegang moet hebben tot het antwoord en geeft het antwoord door aan de client of retourneert een fout.

Voordat een cross-origin verzoek wordt verzonden, voegt de browser automatisch een origin header toe aan het HTTP-verzoek. Deze header, die de client niet kan wijzigen, is een cruciaal onderdeel van CORS en dient om de oorsprong van de client te identificeren (dat wil zeggen het domein, het protocol en de poort waaruit de clientbron is geladen). Deze beveiligingsmaatregel voorkomt dat klanten zich voordoen als andere herkomstlanden. De origin header is fundamenteel voor CORS, omdat het de manier is waarop de client de server vertelt waar het vandaan komt.

In een Cross-Origin Resource Sharing (CORS)-interactie wordt de oorsprong van de client geïdentificeerd door de Origin-header in het eerste verzoek. De server gebruikt vervolgens de Access-Control-Allow-Origin header in zijn reactie om aan te geven of de client toegang heeft tot de gevraagde bron. Deze antwoordkoptekst is cruciaal; als deze afwezig is, mislukt het CORS-verzoek. De Access-Control-Allow-Origin header kan een jokerteken (*) bevatten, waardoor toegang vanaf elke oorsprong mogelijk is, of een specifieke oorsprong, waardoor alleen toegang wordt verleend aan die specifieke client. Terwijl de afbeelding Access-Control-Allow-Origin: * toont, wat impliceert dat CUIC alle oorsprong toestaat, verzendt CUIC deze header meestal met een specifieke oorsprong in realistische scenario's.

Wanneer een browser een CORS-verzoek afwijst, betekent dit dat de client geen informatie ontvangt over de reactie van de server. De klant weet alleen dat er een fout is opgetreden, maar mist details over het specifieke probleem. Dit kan het debuggen van CORS-fouten uitdagend maken, omdat het moeilijk is om een CORS-fout te onderscheiden van andere soorten fouten. Hoewel het eerste verzoek naar de server wordt verzonden, blokkeert de browser de reactie als de reactie van de server geen geldige koptekst voor Access-Control-Allow-Origin bevat en veroorzaakt een fout aan de clientzijde, waardoor de client nooit de gedetailleerde reactie van de server kan zien.

In deze afbeelding wordt het hele CORS-proces uitgelegd, met bijzondere aandacht voor de preflight-fase, die essentieel is voor de afhandeling van specifieke soorten cross-origin-verzoeken.

CORS in actie met Cisco Finesse

Illustratief voorbeeld: CORS-gedrag analyseren met de Live Data Gadget

In deze sectie wordt het typische gebruik van Cross-Origin Resource Sharing (CORS) met Cisco Finesse in contactcenters beschreven. Agenten en supervisors gebruiken vaak Cisco Finesse om toegang te krijgen tot realtime gegevensrapporten (zoals geïllustreerd in de voorbeeldafbeelding).

Wanneer een agent of supervisor op een rapportgadget klikt, initieert hun actie een verzoek om gegevens op te halen. Dit verzoek wordt verzonden vanuit de JavaScript-code van de Finesse-toepassing (die optreedt als de client) naar de CUIC/Live Data-server met behulp van een GET-methode. Zoals aangetoond in de SAML-tracerafbeelding, verzendt de browser eerst een preflight-verzoek naar de server, de CORS-levenscyclus die eerder is beschreven.

Een HTTP OPTIONS-verzoek (het preflight-verzoek) wordt verzonden naar de CUIC/Live Data-server. Dit verzoek specificeert de oorsprong als de volledig gekwalificeerde domeinnaam (FQDN) van de Finesse-server, inclusief poort 8445. Dit is hetzelfde adres en dezelfde poort die agenten gebruiken om toegang te krijgen tot de Cisco Finesse-toepassing.

De opdrachtregelinterface (CLI) geeft op de CUIC/Live Data-serverbesturing aan welke herkomst toegang heeft tot de live gegevensbronnen. Als de oorsprong van de Finesse-server (de FQDN en poort) in deze instellingen is geconfigureerd, kunnen agents de details van de gadget met live gegevens bekijken in Finesse.

TAC-tool voor CORS-verbindingstests

CORS-misconfiguraties aan de serverzijde kunnen soms problemen veroorzaken met gadgets van derden of live-gegevens in Cisco Finesse. Dit artikel bevat een link naar een CORS Quick Check-gadget, een tool voor probleemoplossing die is ontworpen om problemen met Cross-Origin Resource Sharing te diagnosticeren die van invloed zijn op Finesse-gadgets, waaronder live gegevensweergaven en andere integraties van derden.

Technisch gezien werkt deze gadget door preflight-verzoeken van de Cisco Finesse-client naar een opgegeven doelbron te verzenden. Deze snelle controlefunctie helpt om snel CORS-gerelateerde problemen te identificeren en op te lossen, waardoor het proces voor probleemoplossing wordt versneld.

De CORS Quick Check 12.6-v1.0-gadget van Contact Center implementeren in het Finesse-bureaublad:

1. Download gadget bestanden van Contact Center CORS Quick Check 12.6-v1.0 map.2.

2. Kopieer de inhoud van de map Contact Center CORS Quick Check 12.6-v1.0 naar de map 3rdpartygadget in uw Finesse-installatie.

3. Voeg de gadget toe aan de gewenste gebruikersrol (Agent, Supervisor, enzovoort) in de Finesse-desktoplay-out. Het gegeven voorbeeld XML demonstreert de juiste configuratie voor het toevoegen van dit gadget.

<gadget>/3rdpartygadget/files/TestCORSgadget.xml</gadget>

Zie het hoofdstuk Gadgets van derden in de Finesse Developer Guide en het hoofdstuk Gadgets van derden beheren in de Finesse Administration Guide voor meer informatie over het uploaden van gadgets van derden en het toevoegen ervan aan het bureaublad.

Zodra de gadgetbestanden zijn geüpload en de Cisco Finesse Tomcat-service opnieuw is gestart, is de gadget beschikbaar en wordt de grafische gebruikersinterface (GUI) weergegeven.

U kunt CUIC selecteren in de vervolgkeuzelijst bovenaan. Voer in het opgegeven veld de volledig gekwalificeerde domeinnaam (FQDN) van de CUIC-server in. Een geslaagde test zal worden uitgevoerd zoals hier wordt getoond.

Een succesvolle test betekent dat de CUIC-server correct is geconfigureerd voor Cross-Origin Resource Sharing (CORS) met de Finesse-server. Uit de SAML tracer-logs van de browser blijkt dat een HTTP OPTIONS-verzoek (de CORS-preflight) naar de CUIC-server is verzonden. Dit verzoek bevatte het adres van de Finesse-server in de koptekst Origin. De CUIC-server reageerde met een 200 OK HTTP-bericht, en belangrijker nog, de Access-Control-Allow-Origin header in het antwoord bevatte ook het adres van de Finesse-server. Dit bevestigt dat de CUIC-server is geconfigureerd om verzoeken van de oorsprong van de Finesse-server toe te staan, waarbij wordt gecontroleerd of CORS correct is ingesteld.

OPTIONS https://cuicpub.uccelab.tac/cuic/ HTTP/1.1
sec-ch-ua-platform: "Windows"
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome..
sec-ch-ua: "Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"
sec-ch-ua-mobile: ?0
Accept: */*
Origin: https://finessep.uccelab.tac:8445
Sec-Fetch-Site: same-site
Sec-Fetch-Mode: cors
Sec-Fetch-Dest: empty
Referer: https://finessep.uccelab.tac:8445/
Accept-Encoding: gzip, deflate, br, zstd
Accept-Language: en-US,en;q=0.9

HTTP/1.1 200
server: nginx
date: Sat, 08 Feb 2025 01:27:47 GMT
content-length: 0
strict-transport-security: max-age=31536000; includeSubDomains
set-cookie: JSESSIONID=bE73993C4A7C1Fc1b33A7AaF897B8428; Path=/cuic; Secure; HttpOnly; SameSite=Strict
pragma: No-cache
cache-control: no-cache
expires: Thu, 01 Jan 1970 00:00:00 GMT
x-frame-options: SAMEORIGIN
x-xss-protection: 1; mode=block
x-content-type-options: nosniff
content-security-policy: default-src 'self' ; script-src 'self' data: 'unsafe-inline' 'unsafe-eval' ; style-src 'self' data: 'unsafe-inline' blob: ; img-src 'self' data: 'unsafe-inline' ; connect-src 'self' https://cuicpub.uccelab.tac:443 wss://cuicpub.uccelab.tac:443 https://cuicsub.uccelab.tac:443 wss://cuicsub.uccelab.tac:443 ;
vary: origin,access-control-request-method,Access-Control-Request-Headers
access-control-allow-origin: https://finessep.uccelab.tac:8445
access-control-allow-credentials: true
access-control-expose-headers: access-control-allow-origin,access-control-allow-credentials,access-control-max-age,access-control-allow-headers,access-control-allow-methods,access-control-allow-private-network
access-control-max-age: 600
access-control-allow-methods: DELETE,POST,GET,OPTIONS,PUT
access-control-allow-headers: referer,peripheralid,origin,access-control-request-method,locale,accept,authorization,domain,x-requested-with,access-control-request-headers,content-type,access-control-request-private-network,user-agent
allow: GET,POST,OPTIONS,PUT,DELETE

In dit scenario toont de tool een niet-werkende configuratie. In tegenstelling tot het vorige voorbeeld is de Finesse-server niet geconfigureerd als een abonnee op de CUIC-server. In plaats daarvan is het alleen geconfigureerd op de CUIC-uitgever. Als gevolg hiervan mislukt het CORS-preflight-verzoek en reageert de CUIC-server met een HTTP 403 (Verboden)-fout.

OPTIONS https://cuicsub.uccelab.tac/cuic/ HTTP/1.1
Accept: */*
Access-Control-Request-Method: OPTIONS
Origin: https://finessep.uccelab.tac:8445
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome..
Sec-Fetch-Mode: cors
Sec-Fetch-Site: same-site
Sec-Fetch-Dest: empty
Referer: https://finessep.uccelab.tac:8445/
Accept-Encoding: gzip, deflate, br, zstd
Accept-Language: en-US,en;q=0.9

HTTP/1.1 403
server: nginx
date: Sat, 08 Feb 2025 01:54:52 GMT
content-type: text/html;charset=utf-8
content-length: 2143
strict-transport-security: max-age=31536000; includeSubDomains
set-cookie: JSESSIONID=1C7606841B83d7847486c3d18D31cEfD; Path=/cuic; Secure; HttpOnly; SameSite=Strict
pragma: No-cache
cache-control: no-cache
expires: Thu, 01 Jan 1970 00:00:00 GMT
x-frame-options: SAMEORIGIN
x-xss-protection: 1; mode=block
x-content-type-options: nosniff

Zoals u kunt zien aan de uitvoer van de CUIC subscriber command-line interface (CLI), wordt Cisco Finesse niet vermeld. Dit geeft aan dat Finesse momenteel niet is geconfigureerd als een abonnee op deze CUIC-server.

admin:utils cuic cors allowed_origin list
cors_allowedorigins
===========================
1. https://finessep.uccelab.tac
2. https://finesses.uccelab.tac
3. https://finesses.uccelab.tac:8445