AAI@EduHr developers web

developer.aaiedu.hr

Kako implementirati AAI@EduHr Single Sign-On autentifikaciju u .NET web aplikacijama?


Tehnički opis
Komponente sustava
FAQ
Programska podrška
Aplikacije prilagođene AAI@EduHr
Download



www.aaiedu.hr
schema.aaiedu.hr
www.eduroam.hr
pks.aaiedu.hr

Autori: Dubravko Sever, Ana Petković

Datum zadnje izmjene: 31.01.2012.

Potrebna programska podrška:

Microsoft Windows Server 2008 R2 SP1 / Windows 7 Professional;
IIS sa ASP.NET 2.0 modom rada;
.NET 3.0 framework ili noviji;
Microsoft Visual Studio 2005 ili noviji;
Potrebno je instalirati OIOSAML.NET, verziju 1.7.4;
Datoteka dk.nita.saml20.dll prilagođena za 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 autentifikacije, a u sustavu AAI@EduHr koristi se kao autentifikacijski modul za povezivanje .NET aplikacija s AAI@EduHr Single Sign-On servisom.

Procedura za implementaciju OIOSAML autentifikacijskog modula:

Pokrenite Visual Studio i kreirajte novi ASP.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
Dodajte poveznicu na datoteku dk.nita.saml20.dll:
- Označite:
  
  Projekt -> Add Reference...
- Odaberite datoteku dk.nita.saml20.dll
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

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" %>

Instalirajte certifikat (postupak generiranja certifikata) kojim će se potpisivati zaglavlje. Certifikat treba instalirati u Computer Account koristeći MMC Certificates.
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;
Ubacite sljedeće certifikate (oba u DER formatu) među ceritifikate kojima vaš poslužitelj vjeruje.
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"/>	
```
  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.

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 konfiguraciji web.config treba promjeniti putanju do direktorija:

<IDPEndPoints metadata="C:\metadata\>
	<add id="urn:geant:edugain:component:be:aaieduhr:aaiedu.hr">
		<CertificateValidation>
		<add type="dk.nita.saml20.Specification.SelfIssuedCertificateSpecification, dk.nita.saml20"/>
		</CertificateValidation>
	</add>
</IDPEndPoints>

Dohvatite metapodatke s adrese https://login.aaiedu.hr/sso/saml2/idp/metadata.php i spremite ih u gore definiran direktorij metadata pod bilo kojim imenom (npr. aaiedu_metadata.xml).
Objavite kompajliran projekt na web serveru.
Pošaljite na team@aaiedu.hr URL koji pokazuje na 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 analizi 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 autentificiranom 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.