Vanuit Ysis worden er voor een aantal partners OpenID Connect Single Sign-on oplossingen ondersteund. Daarbij is het mogelijk om vanuit een dossier in Ysis met een enkele knop direct in te loggen in een partner systeem en daar dan ook direct in het juiste dossier terecht te komen.
Dit is een tijdbesparende functie als de zelfde gebruikers meerdere applicaties moeten gebruiken.

Let op dat dit geen data integratie is zoals de API documentatie op deze site, maar een Gebruiker/Authorization integratie.
Daarnaast is het zo dat voor het bieden van deze SSO functie er altijd een stukje maatwerk aan de kant van GeriMedica, dus maak vooraf afspraken met ons voor het ondersteunen. Deze pagina is bedoelt voor partners waarmee deze afspraken zijn gemaakt.

Algoritme

De basis voor de SSO is het Open ID connect protocol. Daarnaast is het echter in de meeste gevallen gewenst om vanuit een Ysis dossier direct te landen in een dossier van het ECD. Om dit te ondersteunen kunnen wij het BSN meesturen in de initiële redirect (2). We willen het BSN daarbij wel versleutelen. Hiervoor kunnen wij aan beide kanten een sleutel configureren.
Het is ook mogelijk om de SSO knop in Ysis te tonen op andere schermen dan een dossier. In dat geval wordt er geen BSN meegestuurd in de aanroep. Wij kunnen het meegeven van een BSN ook geheel uitschakelen: stem de wensen af met GeriMedica.

NB: in de meeste gevallen is er een aparte ‘landingpagina’ gescheiden van het eigen product. Als er in het product al een landingspagina ondersteund met Open ID integratie dan kan dit onderscheid buiten beschouwing gelaten worden.

Onze standaard implementatie gaat uit van de volgende Initiële aanroep. Andere aanroepen zijn mogelijk, maar dan graag in overleg met GeriMedica afstemmen.

1) In Ysis drukt de gebruiker op de ‘SSO’ knop boven in Ysis.
Deze knop kan door de applicatiebeheerder van de klant per gebruiker worden geautoriseerd.

2) In Ysis wordt een nieuwe tab in de browser geopend. Daar wordt een redirect gedaan
In Ysis wordt een nieuwe tab in de browser geopend. Daar wordt een redirect gedaan naar de URL die per organisatie kan worden geconfigureerd (let op: maar 1 URL per zorginstelling is mogelijk). Vanuit Ysis wordt de pagina aangeroepen met 2 parameters:

• orgName. Deze geeft de code/unieke organisatie naam aan zoals geconfigureerd in Ysis. Dit maakt het mogelijk dat de URL die wij aanroepen hetzelfde kan zijn (dit staat SAAS oplossingen toe). Deze parameter is bij de OpenID aanroepen nodig voor het identificeren van de zorginstelling.

• bsn. Dit is de BSN van patient van waaruit op de SSO knop is gedrukt. Mocht de patiënt geen BSN hebben, of de knop zijn gebruikt vanuit een overzicht of ander algemeen scherm in Ysis dan is de BSN parameter leeg. Ideaal gezien zouden we dan in een algemene pagina willen landen. Het BSN wordt encrypted volgens een sleutel die per zorginstelling wordt afgestemd.

3) Er kan vervolgens bij Ysis een Open ID code worden opgevraagd.

• URL: GET https://{OrgName}.acceptatie1.ysis.nl/cas/oauth/authorize. Hierbij is de OrgName de waarde bij stap 2. Bij een On-Premise oplossing die voor 1 zorginstelling geldt kan dit eventueel aan uw kant worden geconfigureerd. Maar het gebruiken van de aangeleverde parameter heeft onze voorkeur.
• Required Parameters:
  • response_type = code
  • scope = openid-integration
  • state = some random string (OpenID Standard state)
  • client_id = <Af te stemmen met GeriMedica voor uw OpenID integratie applicatie>
  • redirect_uri = <de url waarop u een callback wilt krijgen>
• onze centrale authenticatie service controleert vervolgens of de gebruiker een sessie heeft, zo niet dan wordt om authorisatie in Ysis gevraagd. Daarna wordt er een CODE gegenereerd en vindt een redirect plaats naar de url die is aangeleverd.

4) De token kan vervolgens worden vertaald in een specifiek Open ID token.
De CODE kan vervolgens gebruike worden om een Open ID token op te vragen.

• URL: POST https://{OrgName}.acceptatie1.ysis.nl/cas/oauth/token
• Body Format = form-data
• Verwachte parameters:
  • client_id = <Af te stemmen met GeriMedica voor uw OpenID integratie applicatie>
  • client_secret = hk90nlv1hgha3agvj9as
  • redirect_uri = <de url waarop u een callback wilt krijgen>
  • grant_type = authorization_code
  • code =  This will be the code obtained from CAS in the previous request

Voorbeeld van een token:
{
  “sub”: “ddc6f417-0f90-420d-a97e-17182f2117b0”,
  “aud”: “ysis-core”,
  “iss”: “https://gerimedica.ysis.nl/“,
  “iat”: 1619769901,
  “exp”: 1619773501,
  “jti”: “ed1f2a18-10a5-4cd6-b730-e7df6056fca9”,
  “kid”: “rsa1”,
  “email”: “<email adress configured in Ysis>”,
  “uid”: “<Ysis User ID (GUID)>”
  “user_name”=”<account name configured in Ysis. Note: only unique within the Ysis customer!>”,
  “user_employee_number”: “<personal number field configured in Ysis>”
  “user_organisation_name”=”<organization name in Ysis>”
}
(zie https://openid.net/specs/draft-jones-json-web-token-07.html#ReservedClaimName voor de ‘reserved names’ van OpenID, maar de meeste zijn niet relevant voor deze koppeling)

5. Authentiseer en land de gebruiker in het juiste dossier
Uw applicatie kan vervolgens de ID_TOKEN signature verifiëren en de bruikbare parameters uit het token halen ter identificatie van de gebruiker.

Als in uw systeem (bijvoorbeeld) ook het personeelsnummer van de zorginstelling wordt geregistreerd kan dit gebruikt worden. Als de klant unieke email adressen per gebruiker heeft kan dat ook worden toegepast. Het is dan wel belangrijk dat de betreffende applicatiebeheerder deze instellingen synchroon houdt en registreert in beide systemen.
Een meer robuuste implementatie die wij adviseren is om bij een onbekende identifier vanuit Ysis eenmalig een inlog te vragen, en daarna deze identifier te registreren. de uid die wij aanleveren is daarvoor erg geschikt: dit is een GUID en identificeert de gebruiker uniek, ook over de zorginstellingen heen.