Overslaan en naar hoofdcontent gaan
English (Europe)

OpenSearch (Enterprise search)

Youri Dechesne
Bijgewerkt

Dit artikel bevat de volgende secties: 


Wat is de OpenSearch koppeling?

OpenSearch is een industrie standaard protocol voor het doorzoekbaar maken van systemen. In het kort is OpenSearch een RSS feed waarbij de resultaten gefilterd zijn op zoekwoorden. Daarnaast biedt de RSS feed idealiter ook paginering voor de zoekresultaten. Mocht een ander systeem in je organisatie dus dit open standaard gebruiken, dan kan je via Embrace vanuit OpenSearch zoeken in deze andere systemen (Enterprise Search).

OpenSearch.png

 

In de basis zijn dit ook de requirements die Embrace stelt aan OpenSearch:

  • RSS feed gefilterd op zoekwoorden
  • resultaten in RSS2.0 / RSS 1.0 / ATOM formaat (vereist)
  • ondersteuning voor paginering (optioneel, eventueel is het ook mogelijk dat de feed bijvoorbeeld altijd max 100 items aanlevert en dat Embrace de paginering afhandelt)

Embrace kan op dit moment alleen andere OpenSearch bronnen raadplegen en niet zelf als bron dienen.

Meer informatie:


Waarom OpenSearch

We krijgen regelmatig verzoeken van klanten om via Embrace in een ander systeem te kunnen zoeken. Tot nu toe betekende dat altijd dat een Embrace ontwikkelaar in C# code moet schrijven op basis van de API van het betreffende systeem. Dit is niet een hele flexibele oplossing. Daarom is er gezocht naar een oplossing waarbij iedere ontwikkelaar in iedere programmeer taal iets kan ontwikkelen. Dit is dan ook het uitgangspunt van OpenSearch ondersteuning door Embrace.

 

Geen Plug and Play

OpenSearch integratie is meestal geen simpele Plug and Play. Er is hiervoor redelijk veel technische kennis nodig en waarschijnlijk ook ondersteuning van een ontwikkelaar. En de kans is groot dat een ontwikkelaar software zal moeten schrijven hiervoor.

 

Buiten scope

OpenSearch biedt een simpele standaard voor eenvoudige zoekopdrachten. Hierdoor zal het volgende niet werken:

  • Het datum filter van Embrace wordt niet doorgegeven aan OpenSearch.
  • Geavancerd zoeken wordt niet goed ondersteund in OpenSearch. Alleen de velden "All deze woorden", "precies deze zin" en "een van deze woorden" worden meegestuurd. Maar de ontvanger kan hier geen onderscheid in maken en zal alleen een standaard zoekopdracht op basis van deze woorden kunnen uitvoeren.

 

OpenSearch authenticatie

In de OpenSearch specificatie is het protocol over zoeken en zoekresultaten gespecificeert. Maar er wordt geen uitspraak gedaan over authenticatie. Om te voorkomen dat in Embrace hele uitgebreide authenticatie mechanismen ingebouwd moeten worden en voor ieder systeem weer een ander mechanisme is er een eenvoudige ondersteuning voor de Authorization HTTP header ingebouwd. Bij het configureren van OpenSearch kan de ruwe waarde van deze header opgegegeven worden.

Hierdoor kunnen authenticatie scenario's ondersteund worden zoals:

  • Anonieme authenticatie (Authorization configuratie leeg laten)
  • Basic authenticatie
  • (OAuth)Tokens authenticatie
  • API key authenticatie
  • etc

Warning: Gebruik deze authenticatie methoden alleen via https!

Embrace werkt dus alleen met voorgedefinieerde authenticatie credentials (systeem accounts) en niet met persoonlijke credentials. Embrace kan wel met elk request een HTTP header meesturen namens wie dat request wordt uitgevoerd. De OpenSearch bron kan deze gebruiken om die persoon te impersonaten en/of zoekresultaten te filteren zodat de gebruiker alleen te zien krijgt waar hij toegang tot heeft.

In de HTTP header "Impersonate-User" wordt dan de UserPrincipalName van de gebruiker meegestuurd.

Let Op: Deze wordt alleen meegestuurd als die bekend is in Embrace. Hiervoor is een profiel synchronisatie zoals de push sync vereist.

Basic authenticatie

Bij basic authenticatie wordt de gebruikersnaam en wachtwoord gescheiden door een dubbele punt en Base64 gecodeerd meegestuurd achter het woord Basic. Bijvoorbeeld gebruikersnaam is demo en wachtwoord is Password1 wordt dan:

Basic ZGVtbzpQYXNzd29yZDE=

(OAuth)Tokens authenticatie

Bij OAuth tokens of Bearer tokens wordt een token opgegeven achter het woord Bearer, bijvoorbeeld:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Ikp vaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Vaak zijn OAuth access tokens 1 uur geldig. Zorg echter ervoor dat in dit geval deze token een lange geldigheidsduur heeft.

API key authenticatie

Custom API key authenticatie lijkt een beetje op voorgaande authenticatie mechanismen. Bijvoorbeeld:

  • ApiKey: klscwdemweodwoicjiowjndfoiwmnfoiwer
  • klscwdemweodwoicjiowjndfoiwmnfoiwer
  • Key: klscwdemweodwoicjiowjndfoiwmnfoiwer


Integratie scenarios

  • Out of the box

    Indien het systeem dat doorzocht moet worden OpenSearch ondersteuning heeft in de vorm die Embrace vereist en indien het systeem overweg kan met 1 van de authenticatie methoden dan kan deze vrij eenvoudig en zonder maatwerk gekoppeld worden.

  • Maatwerk - uitbreiding van het systeem (de OpenSearch bron)

    Als het systeem dat doorzocht moet worden geen OpenSearch ondersteuning heeft of niet overweg kan met de authenticatie methode van Embrace dan kan de leverancier van dit systeem overwegen om dit in te bouwen of aan te passen.

  • Maatwerk - adapter

    Als het systeem dat doorzocht moet worden geen OpenSearch ondersteuning heeft of niet overweg kan met de authenticatie methode van Embrace dan kan er een stukje software geschreven worden dat tussen Embrace en het systeem geplaatst wordt. Dit stukje software kan de OpenSearch request en/of authenticatie van Embrace omzetten naar een specifieke authenticatie en (REST) API van het systeem. En de zoekresultaten weer omzetten naar OpenSearch formaat. Deze software kan in iedere programmeer taal en door iedere ontwikkelaar gemaakt worden. adapter.png


Configuratie

Neem voor configuratie contact op met Embrace support. In Embrace omgevingsbeheer kunnen 1 of meer OpenSearch bronnen opgegeven worden. management.png

Per bron moet opgegeven worden:


Troubleshooting

Mocht een en ander niet correct functioneren dan kan het helpen om met een REST client zoals Insomnia of Postman requests te sturen naar de OpenSearch bron om de werking te controleren.