Doorgaan naar hoofdcontent

 

OCLC Wise Support NL

Hoe gebruik ik de Wise-IAM in mijn externe applicatie?

  1. Laatst bijgewerkt op
  2. Als PDF opslaan

Wat is Wise-IAM 

Wise-IAM is het inlogplatform dat wordt gebruikt door de Wise-applicaties. Wanneer een bibliotheeklid wil inloggen op Wise, wordt de gebruiker doorgestuurd naar het Wise-IAM-platform voor authenticatie. Wise-IAM verifieert vervolgens de identiteit van de gebruiker. Om namens de klant verzoeken te kunnen verzenden naar de Wise API, moet er eerst een authenticatieverzoek worden uitgevoerd om de identiteit van de gebruiker vast te stellen.

  Voor meer informatie over de Wise API, zie Wise REST API. 

  Voor uitleg over wat een "wise_key" is, zie REST API Appendix.

Achtergrondinformatie 

Inloggen met Wise-IAM werkt via het OIDC-principe (OpenID Connect), een authenticatieprotocol. Hier volgt een beknopte uitleg van het OIDC-principe:

  • Wanneer een gebruiker probeert in te loggen bij een client-applicatie, wordt een authenticatieverzoek naar Wise-IAM (het Wise identity platform) gestuurd.
  • Wise-IAM start het inlogproces door de gebruiker om hun inloggegevens te vragen.
  • Na succesvolle authenticatie genereert Wise-IAM tokens, waaronder een access-token, een refresh-token en een id-token. Deze tokens worden teruggestuurd naar de client-applicatie.
  • Met het geldige access-token kan de client toegang krijgen tot beveiligde API's.
  • Wanneer het access-token verloopt, kan de client een nieuw access-token aanvragen met het refresh-token, mits het refresh-token nog geldig is.

Voor het implementeren van OIDC in een applicatie raden wij aan om gebruik te maken van beschikbare openbare libraries:

Uiteraard is het ook mogelijk om andere opties te overwegen.

 

Wise-IAM implementeren 

Aanvragen OIDC configuraties bij OCLC 

Om met je applicatie gebruik te kunnen maken van de Wise-IAM, zullen wij aan onze kant wat zaken moeten configureren. Als je al gebruik maakt van de Wise API, dan hebben we alleen een ‘redirect_url’ (de URL waar de gebruiker door de Wise-IAM heen gestuurd wordt na het inloggen) en een ‘end_session_redirect_url’ (de URL waar de gebruiker heen gestuurd wordt na het uitloggen). Stuur deze gegevens naar de accountmanager van OCLC (carola.schaak@oclc.org).

  Als je nog geen gebruik maakt van Wise endpoints, neem dan contact op de accountmanager van OCLC (carola.schaak@oclc.org).

Bepaal de bibliotheek

  Bibliotheken bij Wise gebruiken verschillende systemen, en dus servers. Vraag bij OCLC aan voor welke bibliotheken de inlogvoorziening moet gelden. 

Ophalen OIDC configuratie 

Om te achterhalen waar het authenticatieverzoek heen gestuurd kan worden, kan het volgende endpoint aangeroepen worden. Voorbeeld in Python: 

import requests 

def get_oidc_config(libraryId, WISE_KEY): 
    URL = baseurl + '/configuration/oidc-client?libraryId=' + libraryId 
    
    headers = { 
        "WISE_KEY" : WISE_KEY
    } 

    try:
        response = requests.get(URL, headers=headers) 
        response.raise_for_status() 
    except requests.exceptions.RequestException as e: 
        print(f"Error: {e}") 
        return[] 
            print(json.dumps(response.json(), indent=2))

Voorbeeld response:

{ 
    "wellknownOidcUrl": "https://iam-emea.wise.oclc.org/realms/een-mooi-realm/.well-known/openid-configuration", 
    "clientId": "local-login-uuid" 
}

Dit endpoint geeft dus het Wise-IAM domein terug (https://iam-emea.wise.oclc.org in het voorbeeld), het realm (“een-mooi-realm” in het voorbeeld), en de clientId (“local-login-uuid” in het voorbeeld).  

In de voorbeeld apps voor Android en IOS op https://github.com/openid wordt rechtstreeks de wellknownOidcUrl en de client Id gebruikt, voor de npm keycloak adapter https://www.npmjs.com/package/keycloak-js  zijn de gescheiden waardes voor Wise-IAM url, realm en clientId nodig.  

De “.well-known/openid_configuration” URL retourneert ook een aantal gegevens die van belang zijn voor het OIDC protocol: 

clipboard_ea308291355c53403609deb30c135c57d.png

Authenticeren

Op basis van de opgehaalde OIDC-configuratie moet een authenticatieproces gestart worden. Dit proces krijgt een ‘access token’ (een JWT) wat gebruikt kan worden om endpoints aan te roepen namens de ingelogde gebruiker met het toevoegen van de authorization als bearer token in de header. Hieronder volgen een aantal voorbeelden voor authenticeren met Javascript en Appauth (SwiftUI).

Javascript

Met de npm keycloak-js library kun je de adapter initialiseren door het volgende code fragment: 

import Keycloak from 'keycloak-js'; 

const keycloak = new Keycloak({ 
    url: 'https://emea-iam.wise.oclc.org', 
    realm: 'een-mooi-realm', 
    clientId: 'local-login-uuid', 
    scope: 'openid patron-actions' 
}); 

try { 
    const authenticated = await keycloak.init(); 
    console.log(`User is ${authenticated ? 'authenticated' : 'not authenticated'}`); 
} catch (error) { 
    console.error('Failed to initialize adapter:', error); 
}

Je kunt het gedrag ook nog beïnvloeden met parameters bij het maken van het Keycloak object, zoals: 

Parameter onLoad: 

  • login-required:  logt de gebruiker automatisch in als de gebruiker al is ingelogd in de Wise-IAM of toont de inlogpagina als de gebruiker niet is ingelogd. 
  • check-sso: logt de gebruiker alleen in als de gebruiker al is ingelogd in de WIse-IAM. Als de gebruiker niet is ingelogd dan wordt de browser geredirect terug naar de applicatie als niet-ingelogde gebruiker. 

Parameter redirectUri: de url waar na het authenticeren naar toe moet worden geredirect door de Wise-IAM (deze url moet bekend zijn in de Wise-IAM) 

Als het Keycloak object met onload check-sso is geïnitialiseerd en je wilt een gebruiker laten inloggen, dan kun je met het volgende statement een inlogsessie starten:

keycloak.login(inlogOpties)

Een inlogOpties is bijvoorbeeld de inlog redirect url. 

Na inloggen zijn in het keycloak object allemaal properties van waardes voorzien, zoals token, tokenParsed, refreshToken, refreshTokenParsed. 

Uitloggen kan met: 

keycloak.login(uitlogOpties)

Een voorbeeld van een uitlogOptie is de uitlog redirectUri. 

De keycloak npm package is summier gedocumenteerd op https://www.keycloak.org/docs/latest...script_adapter.  

Voor meer informatie zou de source van de npm package kunnen worden bekeken op  https://github.com/keycloak/keycloak/blob/main/js/libs/keycloak-js/dist/keycloak.d.ts 

Appauth (SwiftUI voorbeeld)

Met de AppAuth library is het eenvoudig een gebruiker te authenticeren en API requests uit te voeren met verse access tokens. Het proces bestaat uit drie stappen: het ophalen van de OIDC configuratie, het authenticeren van een gebruiker en het daadwerkelijk uitvoeren van een API request. 

Het ophalen van de OIDC configuratie vereist de wellknown OIDC URL die is opgevraagd via de REST API (zie hierboven bij Ophalen OIDC configuratie . De URL kan gebruikt worden in een discovery request. 

let issuer = URL(string: " https://iam-emea.wise.oclc.org/realms/een-mooi-realm/.well-known/openid-configuration ")! 

// discovers endpoints 
OIDAuthorizationService.discoverConfiguration(forIssuer: issuer) { configuration, error in 
  guard let config = configuration else { 
    print("Error retrieving discovery document: \(error?.localizedDescription ?? "Unknown error")") 
    // Return the config or store it in a variable available outside this scope 
    return 
  } 
}

Nu de configuratie beschikbaar is kan het gebruikt worden om een authorisatie request op te bouwen en af te vuren. 

let clientSecret: String? = nil 
let redirectURI = URL(string: "com.bicat.wise.iosapp:/oauth2redirect")! 

// builds authentication request 
let request = OIDAuthorizationRequest(configuration: configuration, 
                                      clientId: clientID, 
                                      clientSecret: clientSecret, 
                                      scopes: ["openid", "patron-actions"], 
                                      redirectURL: redirectURI, 
                                      responseType: OIDResponseTypeCode, 
                                      additionalParameters: nil) 

let scene = UIApplication.shared.connectedScenes.first as? UIWindowScene 

appDelegate.currentAuthorizationFlow = 
    OIDAuthState.authState(byPresenting: request, presenting: self) { authState, error in 
  if let authState = authState { 
    self.setAuthState(authState) 
    print("Got authorization tokens. Access token: " + 
          "\(authState.lastTokenResponse?.accessToken ?? "nil")") 
  } else { 
    print("Authorization error: \(error?.localizedDescription ?? "Unknown error")") 
    self.setAuthState(nil) 
  } 
}

In bovenstaand voorbeeld wordt de authState, wat de response van een succesvol authenticatie request bevat, opgeslagen in een globale variabele. De authState bevat onder andere de refresh en access tokens en is daarom noodzakelijk voor het uitvoeren van API requests. 

Nu de gebruiker is geauthenticeerd kunnen er API requests uitgevoerd worden. Dit kan het beste gedaan worden met de performAction methode van de authSate, deze zorgt er voor dat er altijd een geldig access token gebruikt wordt. 

let userinfoEndpoint = URL(string:" https://{servername}/restapi/library/{libraryId}/patron/{patronSystemId} ")! 
self.authState?.performAction() { (accessToken, idToken, error) in 
 
  if error != nil  { 
    print("Error fetching fresh tokens: \(error?.localizedDescription ?? "Unknown error")") 
    return 
  } 
  guard let accessToken = accessToken else { 
    return 
  } 
 
  // Add Bearer token to request 
  var urlRequest = URLRequest(url: userinfoEndpoint) 
  urlRequest.allHTTPHeaderFields = ["Authorization": "Bearer \(accessToken)"] 
 
  // Perform request... 
}

Meer informatie en voorbeelden zijn te vinden in de READMEs van de Android en iOS AppAuth projecten: 

Verdere informatie

Controleren op abonnement

Het in gebruik nemen van Single Identity middels de Wise-IAM zorgt er voor dat een gebruiker kan inloggen met hun Single Identity account. Dit account hoeft niet een abonnement te hebben binnen de bibliotheek. Als de applicatie daar rekening mee moet houden, kun je het volgend endpoint aanroepen om hier op te controleren. 

Voorbeeld aanroep via Python:

import requests 
def get_subscriptions(): 
    URL = baseurl + '/patron/' + {patronSystemId} + '/subscription' 

    headers = { 
        'WISE_KEY' : {WISE_KEY} 
        'Authorization' : {BEARER ACCESS TOKEN}| 
    } 
     
    try: 
        response = requests.get(URL, headers=headers) 
        response.raise_for_status() 
    except requests.exceptions.RequestException as e: 
        print(f"Error: {e}") 
        return[] 
     
    print(json.dumps(response.json(), indent=2)) 
 
get_subscriptions()

Voorbeeld response:

{ 
  "offset": 0, 
  "limit": 50, 
  "total": 2, 
  "items": [ 
    { 
      "subscriptionId": 65, 
      "service": "BIEB", 
      "description": "55 - 64 jaar", 
      "status": "ACTIVE", 
      "information": "Abonnement: 55 - 64 jaar", 
      "cost": 5000, 
      "startDate": "2024-07-01", 
      "endDate": "2025-06-30", 
      "libraryId": "I003", 
      "branchId": "8901", 
      "sector": "BIEB" 
    }, 
    { 
      "subscriptionId": 65, 
      "service": "BIEB", 
      "description": "55 - 64 jaar", 
      "status": "EXPIRED", 
      "information": "Abonnement: 55 - 64 jaar", 
      "cost": 4750, 
      "startDate": "2023-06-15", 
      "endDate": "2024-06-30", 
      "libraryId": "I003", 
      "branchId": "8901", 
      "sector": "BIEB" 
    } 
  ] 
}

Session expired 

Een access token heeft maar een beperkte geldigheid, wanneer deze is verlopen zal de aangesproken service een 'Session Expired' signaal teruggeven aan de client. De client zal dan een nieuw access token moeten opvragen vanuit Wise-IAM. Hiervoor stuurt de client een token request, met het refresh token op. Als de refresh token ook niet langer geldig is dan zal er opnieuw geauthenticeerd moeten worden. 

De levensduur van dit refresh token wordt door OCLC bepaald maar kan in overleg veranderd worden. 

Voorbeeld Access Token 

Hieronder volgt een voorbeeld Access Token (decoded) van een actieve lener :

{ 
  "exp": 1736853780, 
  "iat": 1736853480, 
  "auth_time": 1736853480, 
  "jti": "4e33baf4-8211-47d5-aa71-b2ab847aa2cd", 
  "iss": "https://testurl.oclc.org/realms/testrealm", 
  "aud": "https://testrealm.oclc.org", 
  "sub": "f:af941b2a-ee02-460d-9f08-2730005ca7a6:65cdc76f0fc34dc08a0eea6ca931e95a", 
  "typ": "Bearer", 
  "azp": "jdfklsajd-325jkldfa3-jklfd", 
  "sid": "8e6fc55e-ec95-48f0-b099-8006b4032b0e", 
  "scope": "openid patron-actions", 
  "wiseUuid": "65cdc76f0fc34dc08a0eea6ca931e95a", 
  "branchId": "8901", 
  "subRealm": "patron", 
  "actorId": "1902008", 
  "libraryId": "I003", 
  "actorName": "bergmans", 
  "sessionId": "9ee35060-3e76-4240-b711-5210438fa687", 
  "sector": "BIEB", 
  "authorities": "MA_CHANGE_EMAIL_ADDRESS,MA_CHANGE_MESSAGE_DELIVERY_PREFERENCES,
  MA_E_MANDATE,MA_SUBSCRIBE_NEW_TITLES_NOTIFICATION,MA_DELEGATE_RENEW,
  MA_VIEW_LOANS,MA_USE_PUBLIC_PRINTER,MA_DELEGATE_PAY,MA_VIEW_WISHLIST,
  MA_VIEW_FINANCIAL_DATA,MA_PLACE_HOLDS,MA_PERSONAL_TITLE_RECOMMENDATIONS,
  MA_PAYMENT_IDEAL,MA_REQUEST_EMAIL_ADDRESS,MA_PLACE_IBL_REQUEST,MA_CANCEL_HOLDS,
  MA_CHANGE_PASSWORD,MA_DELEGATE_PATRON,MA_DELEGATE_COMMUNICATION,MA_VIEW_PATRON_INFORMATION,
  MA_ALLOW_BLOCK_BORROWING_HISTORY,MA_VIEW_HOLDS,MA_VIEW_INBOX,MA_SUBSCRIBE_CWISE" 
}

  Een ‘wiseUuid’ staat ook wel bekend als ‘patronSystemId’ en is nodig om bepaalde endpoints aan te roepen

 

  1. Terug naar boven
  • Was dit artikel nuttig?

Aanbevolen artikelen

  1. Soort artikel
    Onderwerp
  2. Labels
    Deze pagina heeft geen labels.