Page tree
Skip to end of metadata
Go to start of metadata

Inledning

För att en applikation skall kunna integrera mot Ladok krävs en del förberedelser. Förenklat krävs två certifikatsutbyten, dels ett för att klienten (lärosätets system) skall kunna lita på att Ladok verkligen är Ladok, dels ett för att Ladok skall kunna lita på att (lärosätets system) har rätt att ansluta sig. Utöver det behövs viss behörighetshantering, som hanteras på samma sätt som för vanliga fysiska användare Användare och behörighet. Det första utbytet är beroende på vilken miljö integrationen avser. Det andra utbytet hanteras på samma sätt oavsett miljö.

Nedan följer en instruktion som mer i detalj förklarar vilka steg man behöver ta. Innan man börjar bör man bestämma vilket omfång integrationen skall ha. Rekommendationen är att skapa en integration för varje integrationspunkt, vilket i de flesta fall är att likställa med integrerande applikation. Instruktionen nedan bygger på ett exempelscenario där Lunds studentportal ska integrera mot Ladok.

Skapa ett certifikat för en REST-api-användare

Autentisering (identifiering) - Beställa, installera och testa ett certifikat 

Skapa certifikat för MIT-integration, Verifiering-n, Test eller Produktion:

För att skapa ett certifikat för integration mot de dessa miljöer skapar lärosätet (1:st linesupport användare, lokalt ansvarig eller lokal projektledare) ett ärende via  https://www.support.ladok.se där de anger certifikatsuppgifterna i formuläret för tilläggsinformation och skickar in. De uppgifter som efterfrågas är: 

 

  • Ändamål:
  • Common Name (CN) - valfrittnamn@HÖGSKOLEKOD:  
  • Ladokmiljö:
  • Certifikatägare (Förnamn och efternamn):
  • Certifikatägarens e-postadress:
  • Certifikatägarens telefonnummer:
  • Ev. kompletterande information:

 Certifikatägare är här den person/resurs som ansvarar för certifikatet rent tekniskt. Lokalt ansvarig på respektive lärosäte kommer att tillfrågas för godkännande för varje skapat ärende.

Skapa certifikat för MIT, MIT-IK eller resultat:

  1. Skapa ett certifikatärende med mallen i Servicedesk Plus (Tjänstekatalog > Miljöer och certifikat > Beställa certifikat - (REST-gränssnittet och uppföljningsdatabasen) på följande sida: https://www.support.ladok.se
  2. Skapa och ladda upp en CSR. Instruktioner och formulär ligger /certupload/ direkt under rot-url:en för varje miljö. Ex: I MIT-demo är adressen https://www.mit.ladok.se/certupload/  I instruktionen finns också en länk för att hämta hem programvaran openssl som behövs för att skapa en CSR.

  3. Om man tänker sig ett scenario där vi skapar ett certifikat för integration från Lunds studentportal skulle kommandot bli:
    • openssl req -new -newkey rsa:2048 -subj "/CN=studentportal@LU" -out studentportal-LU.csr -keyout studentportal-LU.key
    Kommandot resulterar i att det skapas en CSR-fil och en privat nyckel:
    • Vad gäller CSR-filen, följ instruktionen på sidan certupload. Driften av aktuell Ladok-miljö signerar CSR:en och skickar svar tillbaka till den mejladress som angavs när CSR:en laddades upp. Svaret består av ett signerat certifikat och url till nya Ladoks REST-ingång.
    • Spara filen med den privata nyckeln, den som i exemplet skulle heta "studentportal-LU.key". Kommandot ovan resulterar också i att du är tvungen att ange ett lösenord för denna fil. Se till att spara detta. Du kommer att behöva uppge det senare. 
  4. Spara den publika nyckeln, det certifikat som driften skickar som svar, i vårt exempelscenario skulle det ges namnet studentportal-LU.crt.
  5. Testa att certifikaten fungerar. Gör anrop mha curl mot kataloginformations tjänst för att hämta autentiserad användare, om detta anrop lyckas skapas också en användare i systemet med CN från certifikatet som användarnamn:
    • curl --cert studentportal-LU.crt --key studentportal-LU.key https://api.mit.ladok.se/kataloginformation/anvandare/autentiserad

Skapande av initial integrationsanvändare i Ladok3

Första anropet till systemet med ett nytt certifikat innebär att Ladok-applikationen kommer att skapa en användare i systemet utifrån det CN som finns i certifikatet, i det här fallet studentportal@LU. Just anropet ovan mot /kataloginformation/anvandare/autentiserad returnerar ett Anvandare-objekt med lärosäte, uid, användarnamn, namn och användarens behörigheter - inga i fallet att den precis skapats. När detta är gjort kan en katalogansvarig logga in och tilldela behörigheter till vår integrationsanvändare som därefter kan göra andra slagningar mot systemet. Med samma curl-kommando som ovan kan du sedan kontrollera dina behörigheter i systemet. Genom att skicka xml-datan genom xmllint blir den också lättare att läsa:

  • curl -s --cert <cert> --key <key> https://<api>/kataloginformation/anvandare/autentiserad | xmllint -format -

Auktorisering (behörighet)

Användaren som skapades enligt föregående stycke ska nu ges en uppsättning behörigheter som matchar de REST-anrop som givet integrationsscenario inrymmer. 

  1. Se till att ge den av systemet nyss skapade integrationsanvändaren, i vårt exempel "studentportal@LU", den uppsättning behörigheter som krävs för aktuell integrationsscenario. På varje lärosäte finns en person som har behörighet att administrera användares behörigheter i nya Ladok, normalt den lokala projektledaren för införandet av nya Ladok. Den personen tilldelar integrationsanvändaren en korrekt uppsättning behörigheter. 
  2. Kör om samma anrop som i steg 3 i instruktionen för auktorisering ovan, men byt URL:en mot den REST-tjänst som certifikatanvändaren ska ha tillgång till. Om den har rätt rättigheter skall http-statuskod 200 erhållas.

Begreppslista

I nedanstående tabell visas några begrepp som kan vara bra att känna till innan man börjar följa instruktionerna för autentisering och auktorisering.

BegreppFörklaring
CA-certifikatCA är ett akronym av Certificate Authority och kan översättas till certifikatutfärdare. Ett CA-certifikat är det certifikat med vilket driften signerar det certifikat de skapar upp efter att de erhållit en certifikatsförfrågan. Ett CA-certifikat kallas ibland också rotcertifikat. Mer finns att läsa här.
Certifikat

I vårt fall rör det sig om SSL-certifikat. Det är en typ av elektronisk legitimation. På samma sätt som personer kan legitimera sig med ID-kort eller pass, så kan exempelvis en webbplats legitimera sig med ett SSL-certifikat. I Ladok använder vi ett certifikat som består av en privat och en publik del vilka var och en representeras av en fil. 

  • Publik del - Det av servern signerade certifikat som klienten uppvisar. Driften av nya Ladok skapar och signerar detta med sitt CA-certifikat i vårt fall. Det har oftast en filändelse i stil med "crt" eller "cert".
  • Privat del - En privat nyckel till den publika delen. När man skapar en CSR skapar man den privata delen av certifikatet samtidigt. Den har oftast en filändelse i stil med "key". 

Den privata delen ska man skydda på bästa sätt och aldrig lämna ifrån sig (eftersom den är privat). Mer finns att läsa här.

CSRCSR är ett akronym av Certificate Signing Request. Kort kan sägas att det är en förfrågan om att få ett certifikat signerat. Mer finns att läsa här.
cURLcURL är ett "command line"-verktyg för att hämta och skicka filer genom att använda URL-syntax. Mer finns att läsa här. Ladda ned här.
OpenSSLOpenSSL är en open source-implementation av SSL- och TLS-protokollen, se SSL nedan. Grundbiblioteken implementerar grundläggande krypteringsfunktioner och tillhandahåller en uppsättning kringfunktioner. Mer finns att läsa här. Ladda ned här.
PKCS12Definierar ett filformat för att lagra den privata nyckeln tillsammans med den publika delen skyddat av ett lösenord. Detta format kan innehålla ett till flera objekt (certifikat). I Windows används detta format för att kunna importera privata certifikat till webbläsare. Mer finns att läsa här.
RSAEn krypteringalgoritm som bl a används vid skapandet av certifikat. När man skapar en CSR till nya Ladok använder man denna krypteringsalgoritm. Mer finns att läsa här.
SSLSSL är ett akronym av Secure Sockets Layer och kort kan sägas att det är en säkerhetsmekanism som används för att kryptera kommunikationen mellan två enheter. Mer finns att läsa här.

Test av integration med hjälp av REST-klient, som exempelvis Google Chrome Postman

När du har erhållit ett certifikat och CA-certifikatet som använts för att signera ditt certifikat, gjort ett första anrop med certifikatet mot miljön och tilldelat integrationsanvändaren en korrekt uppsättning behörigheter, så kan du testa att göra ett anrop från valfri REST-klient. Vi har valt Postman, ett tillägg till Google Chrome.

Ta in tilläggsprogrammet Postman

Postman är ett tillägg till Google Chrome. Börja med att lägga till det.

  1. Starta Google Chrome.
  2. Klicka på symbolen för att Anpassa och kontrollera Google Chrome - symbol bestående av tre vågräta streck vilken ligger längst upp till vänster i webbläsaren. En meny visas.
  3. Välj Inställningar i menyn. 
  4. Välj Tillägg bland alternativen till vänster. 
  5. Välj Hämta fler tillägg och sök fram Postman.
  6. Lägg till den app som heter Postman och som är utgiven av www.getpostman.com.

Importera certifikat till Google Chrome

Postman använder sig av de certifikat som finns i Google Chrome för att verifiera klientens identitet. Du behöver importera två certifikat:

  • CA-certifikatet - det certifikat som driften använder för att signera det certifikat du beställer av dem
  • Ditt certifikat i PKCS12-format

Importera CA-certifikat

  1. Klicka på symbolen för att Anpassa och kontrollera Google Chrome - symbol bestående av tre vågräta streck vilken ligger längst upp till vänster i webbläsaren. En meny visas.
  2. Välj Inställningar i menyn.
  3. Välj Visa avancerade inställningar...
  4. Klicka på Hantera certifikat under rubriken HTTPS/SSL
  5. Tryck på Importera... En guide öppnas. 
  6. Bläddra fram det CA-certifikat som driften använt för att signera och som de skickat till dig.
  7. I nästa steg ska du ange i vilket certifikatarkiv certifikat ska placeras. Detta certifikat ska placeras i arkivet för Betrodda rotcertifikatutgivare.
  8. Slutför import-guiden

  9. Kontrollera att CA-certifikatet är importerat och ligger i rätt certifikatarkiv genom att återigen klicka på Hantera certifikat under rubriken HTTPS/SSL och sedan fliken Betrodda certifikatutgivare och leta upp det i listan. 

Importera ditt certifikat i PKCS12-format

  1. Skapa PKCS12-nyckel av ditt certifikat. I vårt exempelscenario skulle kommandot för detta bli:
    openssl pkcs12 -inkey studentportal-LU.key -in studentportal-LU.crt -out studentportal-LU.p12 -export
    OBS! Om du får felmeddelande i stil med "unable to write 'random state'" så prova att köra kommandot som administratör.
  2. Genomför stegen 1-5 under rubriken "Importera CA-certifikat".
  3. Bläddra fram den PKCS12-nyckel som du skapat.
  4. I nästa steg ska du uppge lösenord för detta certifikat. Det är samma som du angav i steg 1 under Autentisering ovan. 
  5. I nästa steg ska du ange i vilket certifikatarkiv certifikatet ska placeras. Detta certifikat ska placeras i det Personliga certifikatarkivet.
  6. Slutför import-guiden

  7. Kontrollera att ditt certifikat är importerat och ligger i rätt certifikatarkiv genom att återigen klicka på Hantera certifikat under rubriken HTTPS/SSL och sedan fliken Privat och leta upp det i listan.

Testa REST-anrop med Postman

  1. Starta Postman. Det här är två sätt att göra det på.
    1. Tryck på ikonen "Appar" längst upp till vänster i webbläsaren (visas i bokmärkesfältet om man valt att genväg för appar ska visas). Klicka sedan på Postman. 
    2. Tryck på Windows startmeny och skriv "postman".
  2. För att göra anropet så enkelt som möjligt ange ett get-anrop som inte kräver några parametrar. Ex: https://api.mit.ladok.se/kataloginformation/anvandare/autentiserad
  3. Tryck på Send.
  4. Första gången du gör ett anrop mot en den maskin till vilken du skapat ett certifikat kommer Postman att be dig välja vilket certifikat som ska användas för att styrka din identitet. I listan ska du hitta det certifikat som du importerat till Google Chrome. Välj det och tryck OK. Om allt är som det ska ska du nu se ett svar i xml-format nedan under Body och fältet Status ska visa "200 OK".

 

För den som vill testa att göra REST-anrop och har möjlighet att göra det mot Ladok3-projektets interna miljöer, följ Instruktion för REST-integration Ladok3:s interna miljöer.

Exempel-applikationer som gör REST-anrop

Du kan testa någon av exempel-applikationerna nedan för att se hur man kan göra anrop i Java respektive .NET. Ladda hem den som passar er utvecklingsplattform och börja laborera. Exempel-integrationerna gör anrop mot testmiljön https://ladok3test.its.umu.se:444. Den maskinen presenterar ett certifikat signerat av Terena, vilket förenklar saken. De allra flesta datorer har Terenas CA så man behöver inte göra något för att åstadkomma steg 1 i instruktionen ovan. Båda exempel-integrationerna innehåller ett certifikat som är signerat for användning mot https://ladok3test.its.umu.se:444 (REST-gränssnitt för ladok3test).

Här är en kort beskrivning av applikationerna:

  1. spring3-resttemplate.zip (Exempel REST-integration, Ladok3-projektet, Java) 
    1. Maven-projekt. Det är alltså möjligt att ta in projektet i något av utvecklingsverktygen IntelliJ eller Eclipse. 
    2. I projektet ligger JAXB-klasser för Examen som har skapats av xjc utifrån XSD-scheman.
    3. Klasserna Ladok3ExamenJerseyClient.java och Ladok3ExamenHandläggningJerseyClient.java jobbar med REST-anrop mot examenstjänsten. Dessa fungerar som körbara klienter. Om man tagit in projektet i ett utvecklingsverktyg så leta rätt på någon av dessa klasser och kör dem. Annars kan man köra dessa klasser från en kommandoprompt. Resultatet av REST-anropen loggas i consolen. 
    4. Klassen Ladok3AtomFeedJerseyClient jobbar med REST-anrop mot feeds. Den fungerar som en körbar klient. Om man tagit in projektet i ett utvecklingsverktyg så leta rätt på denna klass och kör den. Annars kan man köra denna klass från en kommandoprompt. Resultatet av REST-anropen loggas i consolen. 
  2. Enkel-klient.zip (Exempel REST-integration, Ladok3-projektet, .NET)
    1. .NET-projekt
    2. Applikationen läser upp en students studiedeltaganden.

  • No labels