| Dokumentasjonsnytt | |
| Formalia | |
| Faktaark | |
| Håndbøker | |
| Presentasjoner | |
| Spesifikasjoner | |
| Statistikk | |
| Verktøy | |
| Innstillinger | |
| Kontakt oss | |
simpleSAMLphp er en PHP-implementasjon av SAML 2.0-protokollen, og tilbyr en løsning for integrasjon av web-tjenester med Feide med en svært beskjeden ressursinnsats. Utviklingen av simpleSAMLphp startet i Uninett, men er nå et åpen-kildekode-prosjekt med bidrag fra mange miljøer i en rekke land. Prosjektet er ledet fra Uninett.
simpleSAMLphp er egnet for tjenester der webgrensesnittet er basert på PHP. Mange tjenester er basert på moduler programmert i andre språk, som Java eller C/C++, f.eks. for regnskap, lagerhold eller generelle databaser. Dette skaper ingen problemer for simpleSAMLphp så lenge websidene er generert av PHP-kode.
simpleSAMLphp inneholder programkode for begge partene i kommunikasjonen: Både tjenesteleverandør ("SP", Service Provider) som ber om autentisering av en bruker, og identitetsleverandør ("IdP", Identity Provider) som står for autentiseringen. Innenfor Feide er den sentrale driftsorganisasjonen identitetsleverandør. Feide tjenesteleverandører behøver ikke forholde seg til de IdP-rettede funksjonene, og de er ikke behandlet i denne dokumentasjonen.
Som alternativ til SAML 2.0 kan simpleSAMLphp også benytte den eldre protokollen fra Shibboleth 1.3. Dette er normalt ikke relevant i Feide, der SAML 2.0 brukes. Unntaket er dersom en tjenesteleverandør er f.eks. er bundet til å benytte samme løsningen i en rekke land, og av historiske årsaker benyttes Shibboleth 1.3. simpleSAMLphp kan da brukes til å lage en "bro" for konvertering mellom protokollene. For slik bruk henvises til den fullstendige dokumentasjonen på hjemmesidene til simpleSAMLphp: http://rnd.feide.no/simplesamlphp. Her finnes også informasjon om videre arbeide med simpleSAMLphp, samt informasjon om postlister for brukere og utviklere der man kan utveklse erfaringer og ideer. Påmelding gjøres fra hjemmesiden, der du også kan lese tidligere korrespondanse postlistene.
Du finner også komplett dokumentasjon i HTML og PDF-format - dette er særlig aktuelt for brukere som ikke har verkøy for å lese DocBook-formatet benyttet i distribusjonspakken.
Versjon 1.0 av simpleSAMLphp, publisert i mars 2008, er ikke en komplett implementasjon av SAML 2.0-standarden, men all funksjonalitet som er aktuell i Feide er inkludert.
Dette notatet beskriver installasjon av simpleSAMLphp, oppgaver som normalt utføres av driftspersonell som ikke nødvendigvis er rutinert med PHP-programmering, eller kjenner detaljert til programkoden i webtjenesten som vil benytte Feide-innlogging.
Informasjon for programmerere som utvikler PHP-koden for tjenesten finnes i Integrasjon av Feide-tjenester med simpleSAMLphp (faktaark #62).
PHP må være av versjon 5.1.2 eller nyere
simpleSAMLphp er ren PHP-kode, og kan i prinsipp kjøre på alle webtjenere som tilbyr PHP-tolk. Utvikling og testing har vært gjort på Apache. Hvis man står fritt i valg av web-tjener, blir risikoen for uønskede overraskelser minst om Apache blir brukt som webtjener.
simpleSAMLphp er grundigst testet på ulike varianter Linux/Unix og Mac OSX, men kjører også under Windows.
Det er flere alternativer - det første er det mest aktuelle:
Versjon 1.0 av simpleSAMLphp nedlastes som en zip-fil fra
http://code.google.com/p/simplesamlphp/downloads/detail?name=simplesamlphp_1_0.zip&can=2&q=#makechanges.
Ekstraher innholdet til katalogen der du vil plassere simpleSAMLphp; vi kaller den
"installasjons-katalogen". I Linux/Unix-systemer er standard-plassering /var/simplesamlphp/,
men du står fritt til å velge både navn og plassering.
Vilkårlig stabil versjon av programvare fra simpleSAMLphp finnes på http://code.google.com/p/simplesamlphp/downloads/list. (Så lenge simpleSAMLphp kun finnes i versjon 1.0 er dette alternativet svært likt med det første!)
For tilgang til de nyeste feilrettingene og utvidelsene til enhver tid kan du sjekke ut filene i Subversion-arkivet. Gå til installasjonskatalogen og utfør kommandoen:
svn checkout http://simplesamlphp.googlecode.com/svn/trunk/ simplesamlphp
Programvaren utvikles kontinuerlig, og du kan derfor ikke stole på at det som til enhver tid ligger som nyeste utgave i Subversion-arkivet er stabilt og feilfritt!
Maler finnes i underkatalogene config-templates og metadata-templates.
For å unngå at lokale tilpasninger overskrives ved oppgradering, må du ta kopier av relevante
filer til katalogene config og metadata, og redigere på disse kopiene.
Kopier config.php fra config-templates til config.
Kopier saml20-sp-hosted.php og saml20-ido-remote.php
fra metadata-templates til metadata.
NB: Hvis du senere oppgraderer simpleSAMLphp må du ikke kopiere disse malene
til config og metadata
- det vil overskrive hele det lokale oppsettet, og du må gjøre hele tilpasningen på nytt!
Oppsettet for simpleSAMLphp er en PHP-tabell $config,
i fila config.php, indeksert med navnet på en parameter for oppsettet.
Når du redigerer i tabellen, pass på å ikke uforvarende endre på skilletegn, apostrofer etc. -
hvis $config ikke er en formelt korrekt PHP-tabell vil du få en feilmelding
ved oppstarart.
De fleste parametere kan beholdes uforandret. Følgende parametere tilpasses lokalt:
'auth.adminpassword' => '123',
'123' byttes ut med et passord som kun er kjent for adminstrator av webtjeneren.
'technicalcontact_name' => 'Administrator',
'Administrator' byttes ut med navn på den person som er ansvarlig for webtjeneren.
'technicalcontact_email' => 'na@example.org',
'na@example.org' byttes ut med e-postadressen til ansvarlig for webtjeneren.
'default-saml20-idp' => 'max.feide.no',
Behold denne verdien uforandret under uttesting av tjenesten, max.feide.no
er innloggingstjener i testomgivelsene for Feide. Når din tjeneste settes i
regulær drift, endres denne parameteren til 'sam.feide.no', innloggingstjeneren i
produksjonsmiljøet. Flytting fra testmiljø til produksjonsmiljø må koordineres med
Feide, slik at sam.feide.no er forberedt på den nye tjenesten.
Før du gjør denne tilpasningen må du bestemme en entityID - en entydig identifikator - for tjenesten. Feide har regler for hvordan en entityID skal se ut: Les ID og navn for Feide-tjenester (faktaark #51).
metadata/saml20-sp-hosted.php
beskriver din webtjener ("SP" - Service Provider) for simpleSAMLphp.
Fila inneholder en PHP-tabell $metadata som indekseres med tjenestens entityID.
En simpleSAMLphp-installajson kan være felles for mange tjenester, og hver tjeneste har
ett innslag i $metadata-tabellen.
Hvert innslag i $metadata er en tabell indeksert med navnet på en parameter
(tilsvarende $config). Kun én parameter er obligatorisk: Hvilken webjener denne
tjenesten benytter. Legg merke til at både indeksen og verdien av 'host'-attributtet skal redigeres:
Hvis tjenesten har entityID no.byskolen.orakel og kjører på webtjeneren
helpdesk.skole.no vil en tilstrekkelig beskrivelse være:
$metadata = array(
'urn:mace:feide.no:services:no.byskolen.orakel' => array(
'host' => 'helpdesk.byskolen.no'
)
);
metadata/saml20-idp-remote.php beskriver de innloggingstjenestene
("IdP" - Identity Provider) du vil benytte for autentisering av brukere.
I Feide heter tjenesten Moria, og det tilbys en egen innloggingstjeneste
for testformål. Fila inneholder, liksom saml20-sp-hosted.php, en
PHP-tabell $metadata, her indeksert med innloggingstjenestens
entityID.
I simpleSAMLphp-distribusjonen ligger det ferdige innslag både for Feides testomgivelser
og for produksjonsomgivelsene, og du vil normalt ikke behøve å gjøre endringer her.
Verifiser likevel at tabellen har innslag med indeks 'max.feide.no' og
sam.feide.no.
Underkatalogen www i installasjonskatalogen er den eneste som må være
tilgjengelig fra Internett. Her antar vi at din (virtuelle) webtjener har navnet
helpdesk.byskolen.no, med ressursene plassert i katalogen
/var/www/helpdesk.byskolen.no. I Apaches konfigurasjonsfil (standard navn er
conf/httpd.conf i Apache-katalogen) setter du inn en Alias-setning:
<VirtualHost *>
ServerName helpdesk.byskolen.com
DocumentRoot /var/www/helpdesk.byskolen.no
Alias /simplesaml /var/simplesamlphp/www
</VirtualHost>
(Hvis den virtuelle webtjeneren allerede er definert behøver kun Alias-linja tilføyes.)
Du kan nå åpne en webleser til websiden http://helpdesk.byskolen.no/simplesaml
Under overskriften Metadata finner du punktet Hosted SAML 2.0 Service
Provider Metadata (automatically generated). Klikker du her, får du opp en side
med de metadata som Moria trenger for å kunne kommunisere med din tjeneste.
Dagens Moria-implementasjon ønsker data på XML-format. Ta kopi av hele XML-spesifikasjonen,
fra og med <?xml version="1.0" ... til og med den avsluttende
</EntityDescriptor>. Send denne i en e-post til
administrasjon@feide.no, med opplysninger om hvilken tjeneste du tenker
å tilby. Feide vil legge metadataene inn i Moria-tjenesten for Feides testmiljø
(max.feide.no) slik at du kan starte uttesting av tjenesten.
Før tjenesten din blir akseptert i Feides produksjonsmiljø må du ha gjort avtale med Feide om f.eks. hvem som skal ha tilgang til tjenesten og hvilken informasjon om brukerne din tjeneste skal få utlevert. Prosedyrene for dette er beskrevet i Innmelding av en ny Feide-tjeneste (faktaark #52). (Deler av beskrivelsen av medatadata-håndteringen er mindre relevant for tjenester basert på simpleSAMLphp.)
Hvis du er tilknyttet en Feide vertsorganisasjon, har du trolig allerede et Feidenavn
for innlogging. Så lenge du kjører mot Feides testomgivelser må du imidlertid ha et Feidenavn
som er kjent for max.feide.no. Det samme gjelder for tjenesteleverandører som
ikke er Feide vertsorganisasjoner.
Mer informasjon finner du på Feide testbrukere (faktaark #26). Forespørselen om en testbruker kan med fordel sendes inn sammen med metadata for den nye tjenesten.
Nå er alt klart for å at programmererene kan begynne tilpasning av koden i tjenesten til å benytte Feide-autentisering. Dette er behandlet i et eget faktaark, Integrasjon av Feide-tjenester med simpleSAMLphp (faktaark #62).
Når det kommer nye versjoner av simpleSAMLphp, er måten du oppgrader på noe avhengig av hvilke verktøy du bruker for nedlasting og hvilken type oppgradering du ønsker:
Hvis du vil laste ned en stabil revisjon, offentlig publisert som en ny utgave:
config og metadataconfig og metadata tilbake til installasjonskatalogenDet er svært sjelden endringer i formatet på konfigurasjons- og metadatafiler,
men du bør lese gjennom revisjonsloggen, docs/source/simplesamlphp-changelog.xml
i installasjonskatalogen. Ved første oppstart etter oppgradering bør også være særlig oppmerksom
på eventuelle feilmeldinger som kan indikere nødvendige endringer i oppsettet.
Hvis du vil laste ned de nyeste feilrettinger og oppdateringer:
Gå til installasjonskatalogen, og gi kommandoen
svn update
Ulike utgaver av simpleSAMLphp kan lastes ned til alternative installasjonskataloger.
De kan være aktive samtidig: En (virtuell) webtjener henviser til en spesifikk
installasjonskatalog (gjennom Alias-linja i Apache-oppsettet for webtjeneren,
og ulike webtjenere kan henvise til ulike kataloger.
På samme (virtuelle) webjener benytter alle websider samme utgave av simpleSAMLphp.
Den primære hensikten med å kjøre parallelle utgaver av simpleSAMLphp er for å kunne teste ut nye utgaver uten å risikere ustabilitet i den ordinære webtjenesten - særlig viktig når man laster ned oppdateringer utenom de publiserte, stabile utgivelsene. Det kan også være enklere dersom man benytter ulike identitetsleverandører som krever ulike oppsett av simpleSAMLphp.
Webdokumenter tilgjengelig gjennom alternative utgaver kan overlappe fullt ut. "Host"-delen, dvs. det første leddet, av URLen identifiserer en (virtuell) webtjener og bestemmer dermed også hvilken simpleSAMLphp som er aktiv.
Hvis du ikke har installert Subversion, kan den lastes ned fra http://subversion.tigris.org/. Tilpasninger finnes for en lang rekke platformer: Ulike varianter Linux og Unix, Windows, Mac OSX og andre. Kildekode er tilgjengelig.
Hvis du kun laster ned stabile utgaver av simpleSAMLphp har du ikke behov for Subversion; du trenger den kun for å kunne hente de nyeste feilrettinger og utvidelser som enda ikke har blitt med i noen stabil utgave.