Käyttöohje v. 1.0 Päivitetty 21.4.2001 klo 17:28
2 (13) Dokumentin versiohistoria Versio Päivämäärä Tekijä / muutoksen tekijä Selite 1.0 21.4.2001 Parempi kuin edellinen 0.8 19.3.2001 Kosmeettisia muutoksia ja enimmät kirjoitusvirheet pois 0.5 19.3.2001 Mickey Shroff Alustava versio KÄYTTÖOHJE 2
3 (13) Sisällys DOKUMENTIN VERSIOHISTORIA...2 1. JOHDANTO...4 1.1 KÄYTTÄJÄT...4 1.2 YHTEENSOPIVUUS...4 1.3 KÄYTTÖTARKOITUS...4 1.4 YLEISKUVAUS...5 1.5 MÄÄRITELMÄ T, TERMIT JA LYHENTEET...5 1.6 VIITTEET...5 1.7 VIRHERAPORTOINTI...6 2. ASENNUS JA KÄYTTÖÖNOTTO...6 2.1 ASENNUS...6 2.2 KÄYTTÖÖNOTTO...6 3. TOIMINNOT (REFERENCE)...8 3.1 KÄYTTÖTARKOITUS...8 3.2 TOIMINNOT...8 3.2.1 Turvaamattoman komennon luonti...8 3.2.2 Turvatun komennon luonti... 11 3.2.3 Käyttäjien tunnistaminen... 11 3.2.4 Käyttäjä oikeuksien hallinta... 13 3.2.5 Komentojen suorittaminen... 13 4. VIRHEILMOITUKSET... 14 KÄYTTÖOHJE 3
4 (13) 1. JOHDANTO Dokumentti on tarkoitettu käyttöohjeeksi asiakkaan asiantuntijoille, jotka tulevat käyttämään sovelluskehikkoa sovellusten kehitystyössä. 1.1 Käyttäjät Käyttäjäluokkia on kaksi. He ovat ns. Java-ohjelmoijia ja ohjelmistosuunnittelijoita. Ohjelmoijilta vaaditaan vankat perustiedot Java-ohjelmoinnista. Ohjelmistosuunnittelijoiden pitäisi olla perillä patternien periaatteista. 1.2 Yhteensopivuus Koska kyseessä on sovelluskehikko, jonka palvelut mukautetaan kehitettävän ohjelmiston tarpeisiin, se ei aiheuta yhteensopivuusongelmia, vaan lähinnä pyrkii välttämään tällaisten tilanteiden syntymistä. Koska sovelluskehikko on toteutettu Javalla, ei laitteiston yhteensopivuudessa pitäisi aiheutua ongelmia. Sovelluskehikko ei itsessään aseta laitteistoon kohdistuvia vaatimuksia. Ohjelmistoa, jota kehitetään sovelluskehikon palveluiden kautta, asettaa omat sovelluskohtaiset tehovaatimukset laitteistolle. Näin ollen ei laitteistolle voida tässä vaiheessa asettaa muita vaatimuksia, kuin että Java-virtuaalikone pyörii kyseisessä. 1.3 Käyttötarkoitus Sovelluskehikkoa käytetään apuna käyttäjien tunnistamiseen ja käyttäjäoikeuksien hallintaan hajautetussa. Sovelluskehikko toteuttaa kehysrakenteen, jonka toiminnoilla voidaan implementoida erilaisia sovelluksia hajautetussa. Esimerkki tällaisesta sovelluksesta voisi olla weppikauppa, jossa käyttäjien tunnistaminen ja käyttäjäoikeuksien hallinta on keskeisessä asemassa. Sovelluskehikon avulla käyttäjätietokantojen sekä muiden sovelluksen tietokantojen hallinta on helppoa ja hauskaa. Tässä dokumentissa pyritään selvittämään, kuinka sovelluksia voidaan toteuttaa käyttäen apuna sovelluskehikon palveluita. Sovelluskehikkoon saadaan sovelluksen tarvitsemaa toiminnallisuutta toteuttamalla komentoja. Käyttäjäoikeuksien hallinta voidaan toteuttaa sovelluskehikon abstrakteja tietolähderajapintoja periyttämällä. KÄYTTÖOHJE 4
5 (13) 1.4 Yleiskuvaus Lyhyt dokumentin sisäinen kuvaus. Kappale 1 kokonaisuudessaan pohjustaa lukijan kyseiseen aiheeseen. Kappale 2 antaa ohjeet sovelluskehikon asentamiseksi toimintakuntoon. Kappale 3 esittelee, kuinka sovelluskehikon palveluita voidaan käyttää. Kappale 4 esittää sovelluskehikon poikkeukset. 1.5 Määritelmät, termit ja lyhenteet Sovelluskehikko Projektissa toteutettava lopputuote Sovellus Asiakkaan toteuttama sovelluskehikkoa hyödyntävä ohjelma Sovelluskehikon käyttäjä Asiakkaan ohjelmoija, joka käyttää sovelluksen tekemiseen projektissa valmistunutta sovelluskehikkoa Sovelluksen käyttäjä Asiakkaan sovellusta käyttävä henkilö tai prosessi Komento Komento on esimerkiksi jokin operaatio tai toiminto, jonka sovelluksen käyttäjä voi suorittaa sovelluksessa. Oikeus Sovelluksen käyttäjä tarvitsee komennon suorittamiseen oikeuden, joka tarkastetaan ennen kuin komento suoritetaan. Oikeuteen voi sisältyä lipuke. Kredentiaalit Käyttäjätietojen osa, joka sisältää tarpeelliset tiedot käyttäjän oikeuksien tarkistamiseen sovelluksessa. Kredentiaalit koostuvat esimerkiksi käyttäjän yksilöivästä tunnisteesta ja joukosta oikeuksia. 1.6 Viitteet [1] Sovelluskehikon toiminnallinen määrittely, 7.11.2000, versio 1.0 tai uudempi, Mickey Shroff & Timo Lämsä,, http://www.niksula.cs.hut.fi/~jjkankaa//toiminnallinenmaarittely.pdf [2] Sovelluskehikon tekninen määrittely, 21.4.2001, versio 3.1,, http://www.niksula.cs.hut.fi/~jjkankaa//tekninenmaarittely.pdf [3] Sovelluskehikon API-dokumentointi, javadoc, 21.4.2001, versio 1.0, KÄYTTÖOHJE 5
6 (13), http://www.niksula.cs.hut.fi/~jjkankaa//ahmadoc.zip [4] Apachen Jakarta-projektin alla, Log4J-komponentti http://jakarta.apache.org 1.7 Virheraportointi Ongelma tilanteissa yhteyshenkilö Tomas Björnfot vastaa kysymyksiin. Kysymykset voidaan lähettää osoitteeseen tomas.bjornfot@aware.fi. 2. ASENNUS JA KÄYTTÖÖNOTTO 2.1 Asennus Sovelluskehikko toimitetaan jar-paketissa: AHMA.jar. Sovelluskehikon konfigurointi tapahtuu erilaisten tiedostojen avulla, jotka löytyvät config-hakemiston alta. Sovelluskehikon toimivuus voidaan tarkistaa toteuttamalla seuraavat kaksi askelta. 1. Kun testisovellusta halutaan ajaa, täytyy se tehdä siitä hakemistosta, josta config-alihak emisto löytyy. Sovelluskehikon testisovelluksen pitäisi toimia myös silloin, jos config-hakemiston sisältävä hakemisto lisätään luokkapolkuun (ks. toiminallinen määritttely kappale 6.5 Operointi). Sovelluskehikko vie levytilaa n. 2Mb. Kehitysympäristönä käy mikä tahansa Javaa tukeva ympäristö. Sovelluskehikon testaus on suoritettu Windows NT-, Windows 2000- ja Linux-ympäristöissä. Sovelluskehikon käyttö omissa sovelluksissa vaatii oman sovelluksen Javalähdekoodien kääntämisen. Siksi sovelluskehikon käyttöön tarvitaan Javaohjelmointiympäristö. Sovelluskehikko toimii jdk1.2.2. versioista ylöspäin. Asennus vaatii aikaa 10-30 minuuttia riippuen siitä onko sovelluskehikon käyttäjällä Java-ohjelmointiympäristö asennettuna. Asennuksen yhteydessä täytyy mahdollisesti konfiguroida myös tietokanta tms., joka vievät enemmän aikaa. 2. Asennus voidaan tarkistaa onnistuneeksi ajamalla TestClass-sovellus. Jos tämän suoritus menee läpi ilman virheilmoituksia, voidaan sovelluskehikon asennus todentaa onnistuneeksi. TestClass-luokka ja siihen liittymät muut luokat toimitetaan sovelluskehikon mukana. 2.2 Käyttöönotto Ennen sovelluskehikon käyttöönottoa ja esimerkkisovelluksen ajamista, tulisi tämä käyttöohje lukea huolellisesti läpi, turhien ongelmia välttämiseksi. Kappaleessa 2.1 käsitellään sovelluskehikon asennusta. Lisäksi ennen käyttöönottoa ja kehitystyöhön KÄYTTÖOHJE 6
7 (13) ryhtymistä olisi erittäin hyödyllistä lukea sovelluskehikon muuta dokumentaatiota, erityisesti tekninen määrittely [2]. KÄYTTÖOHJE 7
8 (13) 3. TOIMINNOT (REFERENCE) 3.1 Käyttötarkoitus Sovelluskehikko tarjoaa kolmenlaisia palveluita: komentojen luonnin, käyttäjän tunnistamisen ja käyttäjien oikeuksien hallinnan. Komentojen luonti -palvelulla tarkoitetaan toiminnallisuuden lisäämistä sovelluskehikkoon. Tämä tarkoittaa sitä, että komentoja käyttämällä voidaan luoda oman sovelluksen toiminnallisuus. Komennot voivat olla joko turvattuja tai turvaamattomia. Turvaamattomia komentoja voivat suorittaa kaikki käyttäjät, turvattuja komentoja voivat suorittaa vain sellaiset käyttäjät, joilla on tähän oikeudet. Komennon luonti koostuu kolmesta vaiheesta: komentoluokan, komentokohteen ja komentovasteen koodaamisesta. Komentoluokan välityksellä annetaan komennon mahdolliset välitettävät parametrit. Komentokohteessa suoritetaan varsinaiset toimenpiteet, jotka komennolla halutaan saavuttaa. Kun komento suoritetaan, palauttaa se komentovasteen. Komentovasteella voidaan saada mahdolliset palautteet komennon suorittamisesta. Käyttäjien tunnistaminen -palvelu antaa mahdollisuuden tunnistaa sovelluskohtaiset käyttäjät halutulla tavalla. Käyttäjät voidaan tunnistaa lukuisilla tavoilla, kuten sormenjäljistä, verkkokalvosta tai perinteisellä salasana- ja käyttäjätunnus - sanaparilla. Sovelluskehikko antaa siis mahdollisuuden toteuttaa erilaisia käyttäjän tunnistamispalveluita. Käyttäjien oikeuksien hallinta -palvelu mahdollistaa erilaisten käyttäjätasojen määrittelyn. Käyttäjätasoja voi olla esimerkiksi administrator, normal user tai advanced user. Käyttäjien oikeuksia käsitteleviä palveluita voidaan kehittää lisää sovelluskehikon palveluita käyttämällä. 3.2 Toiminnot Kaikista toiminnoista tulee esimerkkikoodit toimitettavan paketin mukana. 3.2.1 Turvaamattoman komennon luonti Tällaisen komennon suorittaminen ei vaadi minkäänlaisia oikeuksia komennon suorittajalta, käyttäjältä. Tämän kaltaisilla komennoilla on siis mahdollista toteuttaa sovellukseen toimintoja, jotka ovat kaikkien käyttäjien käytettävissä (ks. teknillinen määrittely [2]). Seuraavaksi käydään komennon luonti esimerkinomaisesti läpi. KÄYTTÖOHJE 8
9 (13) 3.2.1.1 Komentoluokka Toteutetaan sovelluskehikon tarjoama Command-rajapinta: public class NotSecuredExampleCommand implements Command Tässä toteutettavan komennon luokkanimi on tummennetulla, joka voidaan vapaa valintaisesti valita. Jokaisella komennolla pitää olla ID, jonka avulla sovelluskehikko reitittää komennot komentokohteelle. Tämä ID-string voidaan valita siten, että muilla komennoilla ei ole samaa ID:tä. private final String commandid = "NOT_SECURED_EXAMPLE_COMMAND"; Lisäksi juuri luodun NotSecuredExampleCommand-luokan täytyy toteuttaa getcommandid-metodi, jota sovelluskehikko käyttää tunnistaakseen komennon. public String getcommandid( ) { } return commandid; Ohjelmoija voi lisätä myös omia metodejaan komentoluokkaan. Näitä voidaan käyttää esim. parametrien välittämiseen komentokohteelle. 3.2.1.2 Komentovaste Toteutetaan sovelluskehikon tarjoama Response-rajapinta: public class NotSecuredExampleResponse implements Response Response voi sisältää mitä tahansa tai olla myös tyhjä luokka. 3.2.1.3 Komentokohde Periytetään CommandTarget: public class NotSecuredExampleTarget extends CommandTarget { CommandTarget luokan abstrakti getinstance-metodi täytyy ylikirjoittaa periytetyssä luokassa. Tämän metodin avulla on mahdollista tehdä komentokohteesta singleton. KÄYTTÖOHJE 9
10 (13) public static CommandTarget getinstance() { } throw new UnsupportedOperationException(); execute-metodiin laitetaan kaikki koodi siitä, mitä komennolla halutaan tehdä. Argumentti command sisältää luodun komento-instanssin, jolta voidaan suorittaa omia komentometodeja, jotka sisältävät jonkinlaista tietoa parametreistä. public abstract Response execute(command command); Execute-metodin sisällä myös luodaan instanssi komentovasteesta, joka palautetaan komentoa kutsuvalle oliolle. NotSecuredExampleResponse resp = new etmessage()); NotSecuredExampleResponse(((NotSecuredExampleCommand)command).g 3.2.1.4 Sovelluskehikon konfigurointi Jotta komento voitaisiin käyttöönottaa, täytyy sovelluskehikko konfiguroida huomioimaan juuri luotu komento. Tiedostoon commandfactory.properties täytyy lisätä juuri luodun komennon Id ja sen luokka. Tiedostossa avaimeksi annetaan komennon ID ja arvoksi komentoluokka: NOT_SECURED_EXAMPLE_COMMAND=fi.aware.AHMA.test.NotSecuredExampleC ommand Näin sovelluskehikko saa tiedon siitä mikä ID kuuluu millekin komennolle. Seuraavaksi täytyy huolehtia siitä, että komento menee oikealle komentokohteelle. Tiedosto commandmap.properties on luotu tätä tarkoitusta varten. Tiedostossa avaimeksi annetaan komennon ID ja arvoksi komentokohdeluokka: NOT_SECURED_EXAMPLE_COMMAND=fi.aware.AHMA.test.NotSecuredExampleT arget KÄYTTÖOHJE 10
11 (13) 3.2.2 Turvatun komennon luonti Turvattuja komentoja voidaan käyttää tilanteissa, joissa vain tietyt käyttäjät/käyttäjäryhmät voivat suorittaa vain tiettyjä komentoja (ks. teknillinen määrittely [2]). 3.2.2.1 Komentoluokka Turvattu komento periytetään SecuredCommand-luokasta. Turvatun komennon konstruktorissa pitäisi asettaa komennolle oikeudet lähettämällä sovelluskehykselle komennon ID seuraavasti: Konstruktori() { Permission perm = new Permission(commandId); setpermission(perm); } 3.2.2.2 Komentovaste Tehdään samoin kuin turvaamattomassa komennossa, ks. kappale 3.2.1.2. 3.2.2.3 Komentokohde Tehdään samoin kuin turvaamattomassa komennossa, ks. kappale 3.2.1.3. 3.2.2.4 Sovelluskehikon konfigurointi Komennon ID ja komentokohteen kirjaaminen käy samoin kuin turvaamattomassa komennossa, kunhan ID ja luokkien nimet vaihdetaan oikeiksi. 3.2.3 Käyttäjien tunnistaminen 3.2.3.1 Käyttäjien tunnistaminen käyttäen metodirajapintaa Sovelluskehikossa on jo valmiiksi toteutettu käyttäjätunnus/salasana autentikointi tapa. Sovelluskehikkoon voidaan liittää helposti myös muita, erilaisia autentikointitapoja. Ohje keskittyy kuitenkin vain käyttäjätunnus/salasanaautentikointiin. Käyttäjien tunnistaminen tapahtuu metodirajapintaa käyttäen seuraavasti: KÄYTTÖOHJE 11
12 (13) UseridPasswordAuthentication passwordauth = (UseridPasswordAuthentication)authInst.getInstance(authType); Principal p = passwordauth.authenticate(userid, password); Näin saatua principal-oliota voidaan käyttää turvattujen komentojen suorittamiseen. Principal voidaan hakea erilaisista tietokannoista. Sovelluskehikko on konfiguroitu käyttämään SQL-kantaa (SQLUserDatasource.java) käyttäjätietojen hakemiseen. Käyttäjätietolähdekannassa tulisi aina olla käyttäjätunnus- ja salasanasarake. SQL-käyttäjätietolähteen kentät pitäisi olla varchar-tyyppiä. Jos käyttäjien tunnistamiseen käytetään LPAD:ia, täytyy salanasana-kenttä olla oktetstringtyyppinen. Principal-luokasta periytetty TestPrincipal toimii tällä hetkellä käyttäjätietolähteen pohjana. Tämä kertoo, mitä käyttäjätietoja haetaan kannasta käyttäjän Principalinstanssiin. TestPrincipal-luokan attribuutit, kuten address, password, jne, haetaan automaattisesti käyttäjätietolähdekannasta. Myös atribuutteja vastaavat setteri ja getteri -metodit täytyy toteuttaa. Tämä tapahtuu tutkimalla TestPrincipal-luokan juuri mainittuja attribuutteja. Käyttäjätietolähdekannassa pitäisi myös olla vastaavat sarakkeet samoin nimettynä kuin principal:n attribuutit. 3.2.3.2 Sovelluskehikon konfigurointi Konfigurointitiedostossa AHMA.properties voidaan kyseinen principal vaihtaa omaan principaliin. Alla on TestPrincipal-luokka asetettu Principal-luokaksi. PrincipalClass =TestPrincipal Samassa tiedossa voidaan valita aktiivinen käyttäjätietolähde. Alla olevista riveistä ylemmästä pitäisi ottaa kommentti pois, jos SQL-käyttäjätietolähdettä halutaan käyttää ja LDAP:n vastaava kommentoida. #UserDatasourceConfigFile UserDatasourceConfigFile =config\\sqluserdatasource.properties =config\\ldapuserdatasource.properties Tiedosto SQLUserDatasource.properties sisältää SQL-kannan asetukset, jotka pitäisi vaihtaa omaa SQL-kantaa vastaaviksi. KÄYTTÖOHJE 12
13 (13) 3.2.4 Käyttäjä oikeuksien hallinta 3.2.4.1 Tietokanta Kun halutaan suorittaa turvattu komento, sovelluskehikko hoitaa oikeuksien tarkistamisen. Oikeudet haetaan ns. credentials-tietolähteestä, joka voi olla jokin tietokanta. Tällä hetkellä credentials-tietolähteenä toimii SQL-tietokanta. Credentialstietolähteen kentät pitäisi olla varchar-tyyppiä. Credentials-tietokannassa tulisi aina olla seuraavat sarakkeet: käyttäjätunnus, komennon ID, sekä action string. Turvattujen komentojen oikeuksien tarkistaminen suoritetaan käyttäjätunnuksen ja komennon ID:n perusteella. 3.2.4.2 Sovelluskehikon konfigurointi Tiedostosta AHMA.properties tulisi varmistaa, että rivi CredDatasourceConfigFile =config\\sqlcredentialsdatasource.properties ei ole kommentoituna, jos halutaan käyttää SQL-tietokantaa käyttäjienkredentiaalitietojenlähteenä. SQLCredentialsDatasource.properties tiedostoon voidaan vaihtaa käyttäjätunnus, komennon ID ja action string kentät omaa kantaa vastaaviksi. 3.2.5 Komentojen suorittaminen 3.2.5.1 Sovelluskehikon alustaminen Ennen sovelluskehikon palveluiden ohjelmallista käyttämistä täytyy sovelluskehikko alustaa. Alustaminen tapahtuu seuraavalla staattisella metodikutsulla: CommandManager.init(). 3.2.5.1 Turvaamattoman komennon suorittaminen Turvaamaton komento ei tarvi käyttäjän tunnistamispalveluita, vaan komento voidaan suorittaa sinällään näin: NotSecuredExampleCommand cmd = (NotSecuredExampleCommand)CommandFactory.createCommand("NOT_SECURED _EXAMPLE_COMMAND ) 3.2.4.1 Turvatun komennon suorittaminen Koska turvatun komennon suorittaminen vaati oikeuksien tarkistamisen, täytyy käyttäjä autentikoida ennen komennon suorittamista: KÄYTTÖOHJE 13
14 (13) UseridPasswordAuthentication passwordauth = (UseridPasswordAuthentication)authInst.getInstance(authType); Principal p = passwordauth.authenticate(userid, password); Autentikoinnin seurauksena saadaan käyttöön käyttäjän principal, jonka avulla sovelluskehikko voi päätellä, onko kyseisellä käyttäjällä oikeuksia komennon suorittamiseen. TestCommand testcmd = (TestCommand)CommandManager.getInstance("TEST_COMMAND"); testcmd.setprincipal(p); TestResponse testresp = (TestResponse)CommandManager.execute(testCmd); 4. VIRHEILMOITUKSET Sovelluskehikon omia poikkeuksia ovat (ks. Teknisen määrittelyn luku 8): AuthenticationException, tilanne jolloin käyttäjän tunnistaminen ei onnistu. NoPermissionException, tilanne jolloin käyttäjän oikeudet eivät riitä komennon suorittamiseen. TargetNotFoundException, tilanne joka syntyy, kun komennon kohdetta ei löydy. CommandNotFoundException, tilanne joka syntyy, kun komento luokkaa ei löydy tai sitä ei ole konfiguroitu käytettäväksi sovellukseen. Sovelluskehikko käyttää virheiden ilmoittamiseen ja tallentamiseen Log4Jkomponenttia. Konfigurointitiedossa AHMALog.properties voidaan vaihdella kyseisen komponentin kirjaamistasoja. Apachen weppi-sivuilla [4] on tarkemmat tiedot komponentin toiminnasta ja konfiguroinnista. KÄYTTÖOHJE 14