Potrebna programska podrška
Što je OIOSAML?
Procedura za implementaciju OIOSAML autentikacijskog modula
Generiranje certifikata
Zapisivanje događaja
Uporaba
Što napraviti ako se pojavi pogreška
Važno - Zamjena certifikata 27. 7. 2017.
Potrebna programska podrška
Upute u nastavku realizirane su uporabom sljedeće programske podrške:
- Microsoft Windows Server 2008 R2 SP1 / Windows 7 Professional;
- IIS sa ASP.NET 2.0 modom rada;
- .NET 4.5 framework ili noviji;
- Microsoft Visual Studio 2005 ili noviji;
- Potrebno je instalirati
OIOSAML.NET
, verziju 1.7.9;
- Odgovarajuća DLL datoteka
dk.nita.saml20.dll
prilagođena sustavu AAI@EduHr;
- Datoteka
log4net.dll
- log4net omogućuje napredno logiranje događaja, koje možemo i ne moramo konfigurirati ovisno o tome želimo ili ne dodatno logiranje, ali ova komponenta mora postojati;
- Windows distribucija OpenSSL-a za
generiranje certifikata
;
Što je OIOSAML?
OIOSAML.NET je programski alat za implementaciju SAML2 protokola u .NET web aplikacijama. Ovaj programski alat inicijalno je nastao na temelju projekta Danske vlade za integracijom vladinih servisa u sustav jedinstvene autentikacije, a u sustavu AAI@EduHr koristi se kao autentikacijski modul za povezivanje .NET aplikacija s AAI@EduHr Single Sign-On
servisom.
Procedura za implementaciju OIOSAML autentikacijskog modula
- Pokrenite
Visual Studio
i kreirajte noviASP.NET
projekt:File -> New -> Web Site...
- Dodajte datoteku
dk.nita.saml20.dll
u projekt:
- Označite
Projekt -> Add Existing Item...
- Odaberite datoteku
dk.nita.saml20.dll
- Označite
- Dodajte poveznicu na datoteku
dk.nita.saml20.dll
:
- Označite:
Projekt -> Add Reference...
- Odaberite datoteku
dk.nita.saml20.dll
- Označite:
- Dodajte ASP.NET handlere
login.ashx
,logout.ashx
imetadata.ashx
:
- Označite
Projekt -> Add New Item...
- Iz ponuđenog prozora odaberite
Generic Handler
i upišite ime datotekelogin.ashx
- Ponovite postupak za preostala 2 handlera:
logout.ashx
imetadata.ashx
- Označite
- Promjenite sadržaje generičkih handlera na sljedeći način (svaki postojeći kod handlera treba zakomentirati ili obrisati):
- U
login.ashx
izmjeniti:
<%@ WebHandler Class="dk.nita.saml20.protocol.Saml20SignonHandler" %>
- U
logout.ashx
izmjeniti:
<%@ WebHandler Class="dk.nita.saml20.protocol.Saml20LogoutHandler" %>
- U
metadata.ashx
izmjeniti:
<%@ WebHandler Class="dk.nita.saml20.protocol.Saml20MetadataHandler" %>
- U
- Instalirajte certifikat (
postupak generiranja certifikata
) kojim će se potpisivati zaglavlje. Certifikat treba instalirati uComputer Account
koristećiMMC Certificates.
- Pomoću aplikacije
FindPrivateKey
koju smo dobili s instalacijom OIOSAML-a treba pronaći ključ certifikata za potpisivanje i postaviti mu prava čitanja zaNetwork Service
iIIS_IUSR
:
- Iz komandne linije (
cmd.exe
) pokrenite naredbu:
FindPrivateKey.exe LocalMachine My
Program
FindPrivateKey.exe
nalazi se u distribucijskom paketu za originalni OIOSAML, kad je instaliran na standardnu lokaciju nalazi se u direktoriju C:\Program Files (x86)\dk.nita.saml20\bin;
- Odaberite certifikat i postavite prava čitanja za
Network Service
iIIS_IUSR
;
- Iz komandne linije (
- Koristite prilagođenu konfiguracijsku
web.config
datoteku:
- U
web.config
datoteci pronađite redak:
<SigningCertificate findValue="CN=virtualni-host, DC=organization, DC=hr" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectDistinguishedName" validonly="no"/>
i zamjenite sadržaj atributa
findValue
vrijednošću atributaSubject
u certifikatu kojim će se potpisivati zaglavlja (kriterij pretraživanja MS Certificate Store-a putem DN). Navedeno se može pronaći dvostrukim klikom na certifikat te pregledom poljaSubject
(slika je samo za primjer): - U
web.config
datoteci pronađite redak:
<ServiceProvider id="demoSP" server="http://virtualni-host/">
i zamjenite
id
imenom kojim će se vaša aplikacija predstavljati Single Sign-On servisu, dokserver
treba biti stvarno ime poslužitelja.
- U
web.config
datoteci pronađite redak:
<Audience>demoSP<Audience>
i u vrijednost
Audience
upišite istu vrijednost koja je upisana u poljeid
u prethodnom koraku.
- U
- U korijenu
c:\
kreirajte direktorijmetadata
i postavite mu prava čitanja zaNetwork Service
iIIS_IUSR
. Ukoliko direktorijmetadata
treba biti na nekom drugom mjestu, u konfiguracijskoj datoteciweb.config
treba promjeniti putanju do direktorija:
<IDPEndPoints metadata="C:\metadata\"> <add id="https://login.aaiedu.hr/ms/saml2/idp/metadata.php"> <CertificateValidation> <add type="dk.nita.saml20.Specification.SelfIssuedCertificateSpecification, dk.nita.saml20"/> </CertificateValidation> </add> </IDPEndPoints>
- Dohvatite
metapodatke AAI@EduHr Single Sign-On servisa
i spremite ih u gore definiran direktorijmetadata
pod bilo kojim imenom (npr.aaiedu_metadata.xml
).
- Objavite kompajliran projekt na web serveru.
- Registrirajte vašu aplikaciju u sustavu AAI@EduHr prema uputama na web stranici Sustav jedinstvene autentikacije korisnika.
SAML metapodatke koje je potrebno unijeti prilikom registracije možete pronaći na web adresi (URL) na kojoj se nalazi metadata handler vaše aplikacije, npr.http://vas_posluzitelj.ustanova.hr/metadata.ashx
Generiranje certifikata
Postupak generiranja certifikata (potrebna je OpenSSL
distribucija za Windowse):
- Generirajte 1024 bitni ključ:
openssl genrsa -out openssl_key.pem 1024
- Generirajte certifikat sljedećom naredbom (sve u jednom retku, zamjenite serverName.realm stvarnim DNS nazivom vašeg poslužitelja):
openssl req -new -x509 -key openssl_key.pem -out openssl_crt.pem -outform pem -days 3650 -subj "/CN=serverName.realm"
- Snimite certifikat u pk12 formatu, zajedno s privatnim ključem:
openssl pkcs12 -export -in openssl_crt.pem -inkey openssl_key.pem -out certificate_in_pk12.p12
Zapisivanje događaja
dk.nita.saml20
omogućuje zapisivanje događaja na dvije osnovne razine:
Error
- zapisuje samo pogreške;
Information
- zapisuje događaje unutar sustava i služi za analizu ponašanja sustava u najsitnije detalje;
Podrazumijevana konfiguracija zapisuje samo pogreške u C:\logs\saml2.trace.log
. Kako direktorij C:\logs
standardno ne postoji, potrebno ga je kreirati i postaviti prava pisanja za Network Service
.
Vrstu zapisivanja događaja i odredišni direktorij moguće je promjeniti u datoteci web.config
u odjeljku diagnostics:
<system.diagnostics> <trace autoflush="true"></trace> <sources> <source name="dk.nita.saml20" switchValue="Error"> <listeners> <add name="trace"/> </listeners> </source> </sources> <sharedListeners> <add name="trace" type="System.Diagnostics.XmlWriterTraceListener" initializeData="C:\logs\saml2.tracelog"/> </sharedListeners> </system.diagnostics>
Uporaba
- Podaci o autenticiranom korisniku dohvaćaju se korištenjem property-ja
dk.nita.saml20.identity.Saml20Identity.Current
, primjerice:
if (dk.nita.saml20.identity.Saml20Identity.Current != null) { Saml20Identity test = Saml20Identity.Current; Response.Write("Ispisujem vrijednost za hrEduPersonUniqueID: "); string[] values_ID = test["hrEduPersonUniqueID"][0].AttributeValue; Response.Write(values_ID[0]); Response.Write("<br>"); Response.Write("Ispisujem vrijednost za mail: "); string[] values_mail = test["mail"][0].AttributeValue; Response.Write(values_mail[0]); Response.Write("<br>"); Response.Write("Ispisujem vrijednost za hrEduPersonPrimaryAffiliation: "); string[] values_hrEduPersonPrimaryAffiliation = test["hrEduPersonPrimaryAffiliation"][0].AttributeValue; Response.Write(values_hrEduPersonPrimaryAffiliation[0]); Response.Write("<br> <p size=20>it works</p>"); } else { Response.Write("Neautenticirani korisnik"); Response.Redirect("login.ashx"); } }
- Korisnik se odjavljuje sa sustava pozivanjem
logout.ashx
:
Response.Redirect("logout.ashx");
- Redirekcija na stranicu različitu od
default.aspx
se postiže uporabom koda:
if (dk.nita.saml20.identity.Saml20Identity.Current == null) { dk.nita.saml20.config.SAML20FederationConfig.GetConfig().ServiceProvider.SignOnEndpoint.RedirectUrl = "subweb.aspx"; dk.nita.saml20.config.SAML20FederationConfig.GetConfig().ServiceProvider.SignOnEndpoint.endpointType = EndpointType.SIGNON; Response.Redirect("login.ashx"); }
Što napraviti ako se pojavi pogreška
Stack Trace: [CryptographicException: Keyset does not exist ... ]
U tom slučaju certifikat ne sadrži potrebni privatni ključ za generiranje potpisa ili nisu dobro postavljena prava za čitanje. Ponovite korak 7 ili ponovite postupak generiranja certifikata
.
Važno ! - Zamjena certifikata 27. 7. 2017.
Certifikat koji se koristi za validaciju autentikacijskih odgovora SSO servisa istječe 27. srpnja pa ćemo stoga u četvrtak, 27. 7. 2016. u 7:00 sati postojeći certifikat zamijeniti novim.
Sukladno tome, promijenit će se i SAML metapodaci SSO servisa i u konfiguraciju svake aplikacije koja koristi OIOSAML.NET autentikacijski modul bit će potrebno učitati nove metapodatke prema uputama u koraku 10. u odjeljku Procedura za implementaciju OIOSAML autentikacijskog modula na ovoj stranici.
Metapodaci s novim certifikatom bit će od 27. srpnja od 7:00 sati dostupni na istoj adresi na kojoj su trenutno dostupni metapodaci koji sadrže stari certifikat:
https://login.aaiedu.hr/ms/saml2/idp/metadata.php
Za sve dodatne informacije i eventualna pitanja možete nas kontaktirati slanjem elektroničke pošte na adresu aai@srce.hr.