Autentikacijska i autorizacijska infrastruktura sustava znanosti i visokog obrazovanja u Republici Hrvatskoj
  • Hrvatski
  • English

Implementacija autentikacije putem sustava AAI@EduHr u .NET web aplikacijama

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

  1. Pokrenite Visual Studio i kreirajte novi ASP.NET projekt:

    File -> New -> Web Site...


     
  2. Dodajte datoteku dk.nita.saml20.dll u projekt:
     
    • Označite

      Projekt -> Add Existing Item...

    • Odaberite datoteku dk.nita.saml20.dll


     

  3. Dodajte poveznicu na datoteku dk.nita.saml20.dll:
     
    • Označite:

      Projekt -> Add Reference...


       
    • Odaberite datoteku dk.nita.saml20.dll


     

  4. Dodajte ASP.NET handlere login.ashx, logout.ashx i metadata.ashx:
     
    • Označite

      Projekt -> Add New Item...

    • Iz ponuđenog prozora odaberite Generic Handler i upišite ime datoteke login.ashx

    • Ponovite postupak za preostala 2 handlera: logout.ashx i metadata.ashx


     

  5. 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" %>
  6. Instalirajte certifikat (postupak generiranja certifikata) kojim će se potpisivati zaglavlje. Certifikat treba instalirati u Computer Account koristeći MMC Certificates.

  7. Pomoću aplikacije FindPrivateKey koju smo dobili s instalacijom OIOSAML-a treba pronaći ključ certifikata za potpisivanje i postaviti mu prava čitanja za Network Service i IIS_IUSR:
     
    1. 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;
       

    2. Odaberite certifikat i postavite prava čitanja za Network Service i IIS_IUSR;


     

  8. Koristite prilagođenu konfiguracijsku web.config datoteku:
     
    • Preuzmite datoteku i preimenujte je iz web.config.example u web.config
    • 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 atributa Subject 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 polja Subject (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, dok server 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 polje id u prethodnom koraku.


     

  9. U korijenu c:\ kreirajte direktorij metadata i postavite mu prava čitanja za Network Service i IIS_IUSR. Ukoliko direktorij metadata treba biti na nekom drugom mjestu, u konfiguracijskoj datoteci web.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>
  10. Dohvatite metapodatke AAI@EduHr Single Sign-On servisa i spremite ih u gore definiran direktorij metadata pod bilo kojim imenom (npr. aaiedu_metadata.xml).
     
  11. Objavite kompajliran projekt na web serveru.
     
  12. 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):

  1. Generirajte 1024 bitni ključ:
      
    openssl genrsa -out openssl_key.pem 1024
  2. 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"
  3. 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.