1 Innledning
Personreg er en tjeneste for innhenting av personalia for eksterne som ikke er fast ansatte ved UiO. Løsningen er en del av Prosjekt for Bilagslønn, som i hovedsak består av arbeidsflyt og prosesser i SAPUiO og nettsidene "Personreg" som henter inn opplysninger.
Formålet med tjenesten er å hente inn opplysninger om personer som skal ha overført lønn eller annen økonomisk kompensasjon (timelønn eller kompensasjon for oppdrag) fra SAPUiO, samt tilby digital kontraktinngåelse.
En typisk flyt i systemet vil være
- En saksbehandler starter en ny arbeidsflyt ved å sende en e-postinvitasjon til den eksterne om innhenting av personopplysninger. Invitasjonen består av en unik ID som identifiserer saken. Som et ledd i prosessen vil saksbehandler også sjekke om personen alt har registrert informasjon i SAP.
- Den eksterne får en e-post med informasjon, og en lenke som leder tilbake til personreg for innhenting av personopplysninger. Vedkommende fyller inn et skjema, og sender dette inn.
- Så snart skjemaet er besvart, vil saksbehandler kontrollere opplysningene vha. HR-portalen. Dersom opplysningene blir godkjente, vil man kunne opprette en ny kontrakt til den eksterne.
- Det sendes en ny e-post til den eksterne, med en lenke til Personreg, hvor den eksterne vil kunne se over kontrakten sin, og godkjenne den eller avvise den.
I tillegg er det mulig å hoppe over steg 2 dersom personopplysninger alt finnes i SAP, og har blitt sett over av den eksterne de siste 6 måneder.
Deler av arbeidsflyten utføres i SAP og HR-portalen. Disse oppgavene faller utenfor dette dokumentet.
Flyt fra invitasjon til godkjenning av personopplysninger
Flyt fra invitasjon til godkjenning av kontrakt
Kontaktpunkt for tjenesten
TODO: Fyll inn systemeier og kontaktpunkt
- Systemeier: TODO
- Driftskontakt: TODO
2 Redegjørelse
Personreg er en delleveranse i USIT-prosjektet Bilagslønn. Prosjektet er en del av UiO-prosjektet IHR - Bilagslønn. I prosjektets utredningsfase ble det besluttet at den eksterne skulle benytte seg av tjenesten WebID for autentisering i Personreg. WebID-grupper skulle benyttes for autorisasjon mot enkeltsaker i SAP.
WebID er en tjeneste for løst tilknyttede brukere ved universitetet, noe mange eksterne er. Videre er det mulig å sette opp WebID som autentiseringskilde i Weblogin for hver enkelt tjeneste.
Bruk av WebID, Weblogin, integrasjon mot SAP, samt ressurstilstanden på tidspunktet er årsaken til at utvikling av applikasjonen havnet hos UAIT, til tross for at applikasjonen er en tynn web-frontend. Beslutningen om å utvikle løsningen i PHP hadde flere årsaker:
- Kompetanse og kjennskap til SimpleSAMLphp i gruppen, for integrasjon med Weblogin
- Kompetanse fra- og gjenbruk av kode fra Brukerinfo, Glemt passord og WebID – PHP-applikasjoner tidligere utviklet i gruppen
2.1 Bistand fra Web-seksjonen
Før og under implementasjon av applikasjonen, bistod Web-seksjonen med interaksjonsdesign, samt implementasjon av stilark, maler og invitasjonsapplikasjon i Javascript (AngularJS). Dette arbeidet ble i hovedsak utført av Tomm Eriksen og Rikke Julie Foss-Pedersen.
2.2 WebID-problematikk
Bruk av WebID skapte en del problemer og hodebry, både under utvikling og første runde med pilot:
- Forsinkelse i LDAP-eksport gjorde at den eksterne ikke kunne logge inn med Weblogin umiddelbart etter registrering og/eller innmelding i tilgangsgrupper i WebID. Ved å hente gruppeinformasjon direkte fra WebID i stedet for LDAP, fikk vi redusert denne tiden for noen brukere.
- Manglende støtte for Feide-innlogging i Weblogin. Dersom den eksterne benyttet seg av Feide-autentisering i WebID, ville det ikke være mulig å logge inn i Weblogin. Ved prosjektets oppstart var det antatt at Feide-autentisering i Weblogin ville være klart før prosjektet gikk i pilot.
- Tilbakeføring til Personreg etter registrering og/eller innmelding i tilgangsgruppe. Etter registrering/innmedling i tilgangsgruppe i WebID, var den ansatte "strandet" i WebID-tjenesten, usikker på hva neste steg var. Dette ble forsøkt løst, men var fremdeles utydelig for den eksterne.
- Få tilpasningsmuligheter i WebID gjorde det vanskelig å gi god veiledning og gode tilbakemeldinger til den eksterne.
- Epostkommunikasjon fra to ulike løsninger var forvirrende for eksterne.
- Vanskelig å skjule den tekniske implementasjonen fra sluttbrukere.
WebID viste seg å ikke være egnet for formålet, til tross for at noen av problemene ble forsøkt løst. Flyten ble for komplisert og inkonsekvent for den eksterne, og etter tilbakemeldinger fra pilot ble det besluttet at en alternativ form for autentisering ville være tilsvarende eller mindre kostbart å utvikle, og gi en bedre brukeropplevelse.
2.3 Tokens
Det ble besluttet å benytte token-autentisering for å erstatte bruk av WebID i Personreg. Autentisering av eksterne gjøres da ved at det utstedes autentiseringskoder (tokens). Koden integreres i en URL som sendes til den eksterne på e-post. Denne formen for autentisering var alt brukt i Nettskjema og WebID, og var derfor kjent terreng i USIT. Funksjonaliteten i Nettskjema eller WebID kan imidlertid ikke benyttes uten videre i Personreg – token-autentisering ville kreve en del utviklingsarbeid.
Siden token-autentisering nå ville benyttes i flere tjenester, ble det vurdert å sette opp en generell tjeneste for UiO, men grunnet ressurssituasjonen og tidsfrister ble dette uaktuelt for prosjektet. Det ble heller besluttet å integrere token-autentisering i Personreg-applikasjonen, men med tanke på eventuell integrasjon mot en fremtidig, løsrevet tjeneste for token-autentisering for UiO.
Kombinasjonen av eksisterende tjenester (inkludert Personreg) som benytter tokens for autentisering kan også danne et godt grunnlag for krav til en generell tjeneste.
2.4 SAP-integrasjon
Integrasjon med SAP har vært utfordrende, både med tanke på ressursbruk og forsinkelser. UiO har pressede ressurser med teknisk SAP-kompetanse, og mangler erfaring med SAP Web Services.I tillegg har erfaring vist at oppgraderinger til SAP har endret oppførsel til Web Service, som brekker kommunikasjonen mellom Personreg og SAP. Slike hendelser kan kreve mye ressurser fra SAP-drift for feilsøking i ellers travle perioder.
2.5 Person-knytning
Autentiseringsformen, uavhengig av om det er WebID eller tokens som benyttes, har en svak persontilknytning. I begge tilfeller er det adgang til den eksternes e-postkonto som avgjør om vedkommende får tilgang til tjenesten. Dette ble imidlertid regnet som sterk nok autentisering til formålet.
2.6 Phplib2
Det var tenkt å gjenbruke en del kode fra eksisterende prosjekt – Brukerinfo. For brukerinfo er gjenbrukbar kode samlet i phplib. Siden Brukerinfo skulle gjennom et redesign, ble det besluttet å lage et Phplib2, for så å migrere over funksjonalitet fra phplib hit.
2.7 Nedlegging
1. mai 2021 gikk universitetet over til å bruke et nytt system for økomomi og lønn, som et resultat av prosjektet BOTT-ØL. Det nye systemet vil ha en egen løsning for å innhente personopplysninger for timelønnede og oppdragstakere.
Det er derfor ikke lenger behov for en tjeneste som Personreg, og tjenesten ble skrudd av 30. april 2021.
3 Detaljbeskrivelse
3.1 Teknisk formål
Personreg muliggjør delvis selvbetjent registrering av personalia i SAP, for personer som potensielt ikke har noen tilknytning til UiO. Løsningen erstatter en tung, manuell arbeidsprosess, og reduserer feil i UiOs kildesystem for personaldata, SAP.
Løsningen er en inngangsportal, både for saksbehandlere og eksterne ved inngåelse av nye arbeidskontrakter for prosjektansatte og bilagslønnede.
3.2 Høynivådesign
Personreg er utviklet i PHP, og er en tynn frontend for SAP. Bortsett fra autentiseringstokens og informasjon som lagres i SAP, har ikke applikasjonen noen persistent tilstandsinformasjon. Applikasjonen bygger på en rekke rammeverk som er kjent i gruppen, samt en del nye rammeverk.
Weblogin-integrasjon
Autentisering av saksbehandlere skjer gjennom Weblogin, en SAML2.0 Identity Provider som er satt opp ved UiO. Selve SAML-kommunikasjonen gjøres av en Service Provider som blir satt opp for Personreg, med rammeverket SimpleSAMLphp.
SAP-kommunikasjon
Personreg kommuniserer med en SAP Web Service som er utviklet av Solid Group, i samarbeid med UAIT. Kommunikasjonen skjer med SOAP over HTTPS, og autentisering i tjenesten gjøres av SSL-laget (klientsertifikat).
Kommunikasjonen går gjennom en reverse-proxy som driftes av SAP-drift. Proxyen terminerer ikke SSL-forbindelsen, slik at all trafikk (inklusive klientsertifikat) går direkte fra Personreg-klienten til SAP-WS.
Logging
Nettsidene opererer med to ulike logger:
- Feillogg – benyttes for feilsøking av applikasjonen, og skal ikke logge personspesifike opplysninger.
- Audit-logg – benyttes for å etterprøve tilgangsbruk. Siden applikasjonen benytter en systembruker mot SAP, kan det være nødvendig å se tilbake på hvilke brukere som har benyttet seg av adgangsbegrensede operasjoner mot SAP. Alle kall til eksterne tjenester, samt innlogging og autorisasjonssjekker skal logges her.
3.3 Lavnivå-design
Phplib2
All funksjonalitet som ikke er spesifik for Personreg ble plassert i en egen modul, Phplib2, for gjenbruk i andre webutviklingsprosjekt som havner hos UAIT.
Modulen har alt blitt gjenbrukt i et annet USIT-prosjekt, «Alumniløsning for UiO»
Rammeverk
Rammeverket baserer seg på Symfonys HTTPFoundation- og HTTPKernel-komponenter. Et HTTPKernel-objekt konfigureres med en Dispatcher og en Router.
En typisk flyt gjennom rammeverket blir slik:
- Et Request-objekt bygges for forespurselen, og sendes til HTTPKernel.
- HTTPKernel sender Request-objektet til en Dispatcher, som avgjør hva som skal utføres.
- Dispatcher vil sende Request-objektet gjennom en serie RequestListeners, som hver vil utføre en oppgave basert på informasjonen i Request-objektet. Dette kan f.eks. være avgjøre språkvalg, eller endre tekstenkoding.
- Dispatcher vil så sende requesten til en siste listener – RouterListener. Denne avgjør hvilken funksjon i applikasjonen som genererer en Response for en gitt Request. Dersom ingen passende funksjon finnes, vil det oppstå en feil, og man får generert en Response med HTTP-statuskode 404.
- Applikasjonen genererer et Response-objekt som sendes tilbake til Dispatcher.
- Dispatcher sender Response gjennom en serie ResponseListeners som utfører tilleggsoppgaver for envher Response. Dette kan f.eks. være å legge på HTTP-headers, konvertere tekstenkoding, lagre sesjonsdata eller cookies, og andre lignende oppgaver.
- Dersom en uhåndtert feil oppstår, vil en ErrorListener fange opp dette, og generere en Response for dette, med en passende HTTP-statusmelding.
- Til sist vil en Response (enten fra applikasjonen, eller fra en ErrorListener) sendes til HTTPKernel, som vil gjøre dette om til et HTTP-svar som returneres til klienten.
Autentisering av saksbehandler
Saksbehandlere autentiseres gjennom Weblogin. Applikasjonen må selv sørge for å kreve autentisering der det trengs, men funksjonalitet for å autentisere med Weblogin ligger i rammeverkene Phplib2 og SimpleSAMLphp.
Straks applikasjonen krever autentisering (Phplib2), vil Service Provider (SimpleSAMLphp) ta over kontrollen av applikasjonen. Denne sender brukerens nettleser til den konfigurerte Identity Provider (Weblogin), hvor autentisering utføres ved hjelp av brukernavn og passord som verifiseres mot LDAP. Identity Provider vil så sende brukerens nettleser tilbake til Service Provider. Denne vil så sende brukeren til siden som krevde autentisering.
Autentisering av eksterne
TODO: Token-autentisering
Autorisasjon
Autorisasjon styres av SAP. Saksbehandlere er registrert i SAP med spesifike roller. Disse rollene gir tilgang til grensesnittet for saksbehandlere i applikasjonen. For å finne ut om en person har tilgang til dette grensesnittet, spør applikasjonen SAP-WS om det autentiserte brukernavnet har riktig rolle i SAP.
TODO: Hvilken rolle gir saksbehandlertilgang?
Eksterne autentiseres vha. tokens, som inneholder informasjon om hvilken sak i SAP tokenet gjelder for. Dersom SAP-saken er i en tilstand som venter oppfølging av den eksterne, så er den eksterne autorisert til å utføre oppgaven som fører saken videre i SAP.
Kommunikasjon med SAP
I kommunikasjon med SAP, benyttes PHPs SoapClient som basis. Denne er pakket inn av Phplib2, i en klient som har mulighet til å utføre enkelte ekstraoppgaver, som å sjekke om klienten kan nåes, og validere SSL-sertifikater.
Dependency injection
Applikasjonen benytter seg av dependency injection for enkelte objekttyper. Dette gjelder typisk globale objekt, samt objekt som krever en del global konfigurasjon. For dette benyttes en enkel Factory-klasse for å fremstille og cache disse objektene.
4 Avhengigheter
4.1 Systemer som Personreg er avhengig av
- SAPUiO – spesifikt en SAP-WS utviklet av Solid Group og UAIT for Personreg. Personreg er kun et grensesnitt for denne tjenesten, og har en sterk avhengighet til denne tjenesten.
- Weblogin – for autentisering. Saksbehandlere vil autentisere seg gjennom Weblogin, og vil ikke kunne benytte Personreg dersom Weblogin er utilgjengelig. Det vil imidlertid være mulig å konfigurere tjenesten til å benytte seg av andre SAML2 IdP-er for autentisering (f.eks. Feide).
4.2 Eksterne komponenter som Personreg benytter seg av
- Symfony – Symfony er et web-rammeverk for PHP. Flere rammeverk ble vurdert (CodeIgniter, Zend). Modularitet gjorde at valget falt på Symfony.
- Twig – Twig er et relativt nytt template-rammeverk. Twig bygger på Jinja2 for Python, og har god støtte i Symfony. Også vurdert: PHP uten egen template engine, CodeIgniters egen templatingsystem, Zend themes, phplib/brukerinfos template-system.
- SimpleSAMLphp – SimpleSAMLphp er et godt, komplett og enkelt rammeverk for SAML-kommunikasjon. Ingen andre rammeverk ble vurdert.
- PHPMailer – PHPMailer var alt i bruk i WebID, og var derfor kjent for gruppen. Ingen andre verktøy for utsending av e-post ble vurdert.
- HTML_QuickForm2 – HTML_QuickForm2 er en videreutvikling av HTML_QuickForm, som benyttes av Brukerinfo og WebID. Nytt i HTML_QucikForm2 er generering av Javascript-kode for validering på klientside i tillegg til Server-side validering av skjema. Valget av HTML_QuickForm2 har bydd på noe problemer, da rammeverket ikke er veldig modulært eller tilpasset moderne PHP-rammeverk.
- Monolog – Monolog er et komplett rammeverk for logging, og støtter logging til fil, PHP error_log, syslog, ElasticSearch og stort sett hva enn man måtte ønske. Monolog ble tatt inn for å erstatte PHPs error_log for utviklere.
- TODO: Doctrine, eller evt. andre SQL-, DBAL-, ORM-rammevert
Noen av komponentene har også avhengigheter som må være tilgjengelig. Løsningen benytter seg av Composer for nedlasting av avhengigheter, og innlasting av komponenter.
Enkelte komponenter kan erstattes av med versjoner fra EPEL (og PEAR der tilgjengelig), med unntak av SimpleSAMLphp. Dersom man installerer HTML_QuickForm2 gjennom PEAR, vil dette kreve litt ekstra manuelt arbeid for å publisere javascript som følger med komponenten.
5 Relaterte system
- HR-portalen – for personregistrering, deler av personreg-prosessen utføres også her
- Alumniløsning for UiO – deler mye kodebase og design med Personreg (Phplib2)
6 Lenker og referanser
- WebID
- Weblogin – Informasjonssider om Weblogin
- Alumniløsning for UiO – Nettsted for USIT-prosjektet Alumniløsning for UiO, en annen løsning som benytter Phplib2.
- HR-portalen
- Prosjektsiden for Bilagslønn – Nettsted for USIT-prosjektet Bilagslønn
- Bitbucket – phplib – Kildekode for phplib
- Bitbucket – Phplib2 – Kildekode i Phplib2
- Bitbucket – Personreg – Kildekode for Personreg