1 Versjonskontroll

Dato Oppdatert av Versjon Beskrivelse av endringer
29.3.2009 Ronny Blom 1.0 Dokument opprettet
15.4.2009 Ronny Blom 1.0 Dokument endret etter tilbakemeldinger fra Tor Ivar Iversen
2.6.2009 Ronny Blom 1.0 Dokument klargjort for release
25.1.2010 Ronny Blom 3.1 Dokument gjennomgått og versjon satt til 3.1 for å stemme overens med annen dokumentasjon og løsningen
22.4.2010 Ronny Blom 3.1 Endret installasjonsrutine for oppgradering (kapitel 5.2).
14.6.2011 Ronny Blom 4.0 Dokument endret ifm Buddy 4.0

2 Forkortelser

Tekst Forkortelse
Microsoft Identity Integration Server MIIS
Connector Space CS
Management Agent MA
Metaverse MV
Dynamic Link Library DLL
Active Directory Application Mode ADAM
Active Directory AD
Global Address List GAL
Microsoft Password Change Notification Service PCNS
Service principal name SPN
Remote Procedure Call RPC
Distinguished Name DN
Local Security Authority LSA
Secure Socket Layer SSL
Hypertext Transfer Protocol HTTP
Hypertext Transfer Protocol over Secure Socket Layer HTTPS

BBWEB er utviklet i .NET versjon 2.0. Det er derfor viktig at .NET versjon 2.0 eller høyere (for eksempel 2.0.50727) er installert på serveren hvor web løsningen skal kjøres. Det kreves også at ASP.NET AJAX 1.0 installeres på web server. Både ASP.NET 2.0 og ASP.NET AJAX 1.0 kan lastes ned fra Microsofts hjemmeside.

BBWEB benytter både databasen dbMetakatalog og LDAP oppslag mot domene konfigurert i tabellen tblMAProperties. Det er derfor viktig at løsningen kjøres i context av en bruker som har rettigheter til å både koble seg opp mot databasen og kunne logge seg på domenene.

3 KRAV

BBWEB er utviklet i .NET versjon 2.0. Det er derfor viktig at .NET versjon 2.0 eller høyere (for eksempel 2.0.50727) er installert på serveren hvor web løsningen skal kjøres. Det kreves også at ASP.NET AJAX 1.0 installeres på web server. Både ASP.NET 2.0 og ASP.NET AJAX 1.0 kan lastes ned fra Microsofts hjemmeside.

BBWEB benytter både databasen dbMetakatalog og LDAP oppslag mot domene konfigurert i tabellen tblMAProperties. Det er derfor viktig at løsningen kjøres i context av en bruker som har rettigheter til å både koble seg opp mot databasen og kunne logge seg på domenene.

4 INFORMASJON

Når det i dokumentet refereres til mapper så menes det, om ikke annet er beskrevet, mapper som ligger i katalogen ’Buddy Version 4.0’.

I dette dokumentet benyttes IIS 6.0 som referanse når løsningen installeres. Dersom IIS 7.0 benyttes er følgende punkter viktig:

Når løsningen er ferdig satt opp vil det kun være brukere som er medlem av gruppen eller gruppene som er angitt som administrator for løsningen (i web.config fil) som vil ha tilgang til å logge på løsningen. Før løsningen skal tas i bruk av andre brukere må rettigheter settes opp. Hvordan rettigheter bør settes opp er beskrevet i systemdokumentasjonen til web løsningen.

5 INSTALLASJON

5.1 Nyinstallasjon

BBWEB installeres på følgende måte:

  1. Kopier mappen “BBWEB” fra mappen “Installer Buddy Versjon 4.0” til ønsket område på web server.
  2. Gjør nødvendige endringer i filen ’web.config’ (se eget kapittel).
  3. Gjør nødvendige endringer for å på din logo presentert (se eget kapittel).
  4. Start ’Internet Information Services (IIS) Manager’ på web serveren.
  5. Kontroller at det finnes en ’Application Pool’ som kan benyttes for ASP.NET versjon 2.0 (eller høyere).
  6. Marker ’Web Sites’ og velg ’Action --> New --> Web Site…’ fra menyen.
  7. Trykk ’Next’.
  8. Skriv inn en passende beskrivelse for web siden, for eksempel ’BBWEB’, og trykk ’Next’.
  9. Sett opp IP og port innstillinger og trykk ’Next’.
  10. Angi stien til mappen ’BBWEB’, kopiert i punkt 1, og trykk ’Next’.
  11. Hak av for ’Read’ og ’Run scripts (such as ASP)’ og trykk ’Next’.
  12. Trykk ’Finish’
  13. Marker web siden ’BBWEB’ og velg ’Actions --> Properties’ fra menyen.
  14. Velg fanen ’Home Directory’ og kontroller at rett ’Application pool’ er valgt (ref. punkt 5).
  15. Velg fanen ’ASP.NET’ og kontroller at rett ASP.NET versjon er angitt. Hvis ikke velg ASP.NET versjon 2.0 (eller høyere).
  16. Dersom det er ønskelig at påloggingssiden skal vises når adressen til web siden åpnes i en internett browser må filen ’Logon.aspx’ (i mappen ’BBWEB’) legges inn øverst i ’default content page’ under fanen ’Documents’.
  17. Valg fanen ’Directory Security’ og trykk på knappen ’Edit’.
  18. Trykk på knappen ’Browse’.
  19. Du skal nå velge en bruker som har tillatelse til å koble seg til databasen dbMetakatalog. Dette er normalt en domene bruker. Velg det domenet som brukeren er medlem av og søk opp brukeren.
  20. Når du har lokalisert brukeren marker denne og trykk ’OK’.
  21. Angi passordet til brukeren og trykk ’OK’. Angi passordet på nytt for å bekrefte det.
  22. Trykk ’OK’ for å lagre og lukke egenskapssiden for BBWEB.
  23. Applikasjonen skal nå være klar til bruk.

Merk! For at bytte av passord via web løsningen skal fungere må det kontrolleres at IIS server er ”Enablet for delegation” på domene kontrolleren(e). For mer informasjon se:

http://kbalertz.com/326089/Enable-Kerberos-Controller-Applications.aspx

5.2 Oppgradering

  1. Ta sikkerhetskopi av alt eksisterende innehold i “BBWEB” mappe.
  2. BBWEB oppgraderes ved å først slette alle eksisterende filer i 'Bin' (BBWEB) mappen på webserveren og kopiere over filene fra 'Bin' mappen i versjon 4.0.
  3. Slett så alle filer i mappen 'Secure' utenom filen 'web.config'.
  4. Kopier deretter over alle filer (utenom filen 'web.config') fra mappen 'Secure' i versjon 4.0 til den eksisterende mappen 'Secure'.
  5. Slett filene 'BuddySamarbeidet.master', 'Default.aspx' og 'Logon.aspx' i BBWEB mappen på webserveren og erstatt disse med de samme filene fra versjon 4.0.

OBS! Dersom du velger å kopiere hele mappen (BBWEB) og overskrive alle filene vil alle endringer og tilpasninger som er gjort bli borte. Filen 'web.config' er særdeles viktig å ikke skrive over.

6 KONFIGURASJON AV DATABASE OG WEB.CONFIG

BBWEB benytter filen web.config for å hente ut informasjon om hvordan løsningen skal koble seg til database, samt kontrollere autentisering mot et eller flere domener. OBS! BBWEB har to web.config filer. Det er kun den web.config filen som ligger direkte i mappen BBWEB som skal endres på. Den andre, som er lokalisert i mappen Secure i mappen BBWEB er for å styre tilgang til sikre sider.

Domene som kan benyttes til pålogging i løsningen defineres dels i databasen dbMetakatalog i tabellen tblMAProperties og dels i web.config. Det er derfor viktig at det tas hensyn til dette og at eventuelle endringer og justeringer gjøres på begge stedene samtidig.

Før web.config endres tilpasses det hvilke domener som skal kunne benyttes til pålogging i databasen dbMetakatalog. Dette gjøres på følgende måte:

  1. Start ’SQL Server Management Studio’ (SQL Server 2005) eller ’Query Analyzer’ (SQL Server 2003).
  2. Koble til databasen ’dbMetakatalog’.
  3. Åpne tabellen ’tblMAProperties’.
  4. Det kan kun tilbys pålogging mot Active Directory domener så det kun disse som skal endres.
  5. Angi unike navn for de ulike domenene, som det skal kunne logges på mot, i feltet ’WebMembershipProviderName’. For eksempel kan navnet angis på følgende måte '[verdi i feltet DomainName]_LoginMembershipProvider'.
    D.v.s. at det for et domene med verdien ’Abante’ i feltet DomainName så vil verdien i ’WebMembershipProviderName’ bli ’Abante_LoginMembershipProvider’.
  6. Angi WebAuthenticationType for de ulike domenene, som det skal kunne logges på mot. Verdien settes til ’Secure’ hvis domenet kun støtter sikker kommunikasjon via LDAP og til ’SecureSocketLayer’ hvis domenet støtter SSL kommunikasjon via LDAP.
  7. Åpne tabellen tblParams. I raden EMAIL EXTENSION fyll inn riktig organisasjonsnummer og mail extension, for eksempel 12345678|@skole.test.no. Hvis flere organisasjoner, skilles disse ved semikolon, eksempel: 12345678|@skole.test.no;987654321|@skole.test2.no.

  8. Du kan nå lukke databaseverkøyet, men noter navnene som er benyttet.

Konfigurasjon av web.config gjøres på følgende måte:

  1. Åpne filen web.config (i mappen BBWEB) i et tekstediterings verktøy, for eksempel Notepad.exe.
  2. Søk opp elementet som heter ’membership’.
  3. For hvert domene det er ønskelig å kunne logges på mot legges følgende inn mellom elementet ’providers’ under ’membership’ elementet: <add name=”[navn angitt i feltet ’WebMembershipProviderName’ i tabellen tblMAProperties]” type=”System.Web.Security.ActiveDirectoryMembershipProvider, System.Web, Version=2.0.0.0,Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" connectionStringName="[Domenenavn]_ADConnectionString" attributeMapUsername="sAMAccountName" enableSearchMethods="true"/>

    For eksempel:

    <add name="Abante_LoginMembershipProvider" type="System.Web.Security.ActiveDirectoryMembershipProvider, System.Web, Version=2.0.0.0,Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" connectionStringName="Abante_ADConnectionString" attributeMapUsername="sAMAccountName" enableSearchMethods="true"/>

  4. I elementet ’membership’ skal verdien i attributtet ’defaultProvider’ settes til navnet på den ’provider’ som skal være default. Elementet ser slik ut:

    <membership defaultProvider="[navn angitt i feltet’ WebMembershipProviderName’ i tabellen tblMAProperties]">

    Dette endres slik at det for eksempel ser slik ut:

    <membership defaultProvider="Abante_LoginMembershipProvider">

  5. For hvert element som er lagt inn under ’providers’ må det nå skapes tilkoblingsstrenger for det navnet som er angitt i parametere ’connectionStringName’ ovenfor. Disse skal legges inn mellom elementet ’connectionStrings’ som finnes helt i slutten av filen. Her legges følgende inn for hvert enkelt element definert under ’providers’:

    <add name="[Domenenavn]_ADConnectionString" connectionString="LDAP://[FQDN til domene server]/[DNS domene navn]"/>

    For eksempel:

    <add name="Abante_ADConnectionString" connectionString="LDAP://AbanteAD1.abante.lab/DC=abante,DC=lab"/>

  6. For at løsningen skal klare å koble seg til databasen dbMetakatalog må tilkoblingsstrengen tilpasses. Tilkoblingsstrengen for dbMetakatalog er forhåndsdefinert og er lokalisert mellom elementet ’connectionsstrings’. Den forhåndsdefinerte tilkoblingsstrengen ser slik ut:

    <add name="dbMetakatalog" providerName="System.Data.SqlClient" connectionString="Server=[Servernavn\Instans];Integrated Security=True;Database=dbMetakatalog"/>

    Det er informasjonen [Servernavn] som skal tilpasses. Når databasen dbMetakatalog ligger på en instans kan den ferdige tilkoblingsstrengen se slik ut:

    <add name="dbMetakatalog" providerName="System.Data.SqlClient" connectionString="Server=AbanteDB1\Buddy;Integrated Security=True;Database=dbMetakatalog"/>

    Når databasen dbMetakatalog ligger direkte på databaseserveren kan den ferdige tilkoblingsstrengen se slik ut:

    <add name="dbMetakatalog" providerName="System.Data.SqlClient" connectionString="Server=AbanteDB1;Integrated Security=True;Database=dbMetakatalog"/>

  7. BBWEB har en egen innebygd rettighetskontroll. Ved installasjon er det ingen brukere som har tilgang til å logge på løsningen eller benytte funksjonalitet i den. For at det skal være mulig å logge på løsningen må det angis en eller flere grupper som inneholder brukere som skal være administratorer for løsningen. Administrator grupper angis under elementet ’appSettings’ i element som har nøkkel ’AdministratorGroups’. Den forhåndsdefinerte konfigurasjonen som skal endres ser slik ut:

    <add key="AdministratorGroups" value="[domene]\[gruppe navn]" />

    Dersom det er flere grupper som inneholder brukere som skal være administrator for løsningen legges de inn fortløpende adskilt med semikolon. For eksempel slik:

    <add key="AdministratorGroups" value="[domene]\[gruppe 1 navn];[domene]\[gruppe 2 navn]" />

    Dersom du ønsker at alle brukere i gruppen Domain Admins skal være administratorer for løsning kan det se slik:

  8. BBWEB er klargjort for å kunne installeres i flere ulike miljøer (for eksempel en installasjon i Administrasjonsnett og en installasjon i Undervisningsnett). For å forhindre at brukere velger feil domene å logge på ved pålogging kan man angi hvilke domener som skal vises i listen over domener ved å angi dette i web.config filen under elementet ’appSettings’ i element som har nøkkel ’LoggOnMAs’. Den forhåndsdefinerte konfigurasjonen som skal endres ser slik ut:

    <add key="LoggOnMAs" value="[MAID fra tabellen tblMAProperties]" />

    Dersom det er kun et domene som skal vises i listen så angis MAID som dette domenet har i tabellen tblMAProperties i databasen dbMetakatalog. For eksempel slik:

    <add key="LoggOnMAs" value="AD MA " />

    Dersom det er flere domener som skal vises i listen så angis MAID for alle domenen adskilt med semikolon. For eksempel slik:

    <add key="LoggOnMAs" value="ADMIN AD MA;UNDERVISNING AD MA" />

Se for øvrig vedlegg ”Eksempel web.config” for en fullstendig fil.

7 ENDRING AV LOGO

For å endre logo som vises i løsningen må følgende gjøres:

  1. Finn en passende logo. Den må være på billedformatet JPEG (med filendelse JPG) og bør være ca. 600 x 100 pixler.
  2. Lagre bildet med navnet ’logo.jpg’ og plasser det i mappen Grapichs i mappen BBWEB.
  3. Kontroller hvordan bildet vises i løsningen web å åpne adressen til løsningen i en internett browser.

OBS! Før det gjøres endringer i CSS filen bør det tas kopi av den slik at man kan legge tilbake denne dersom det skulle bli noe feil.

Dersom det er nødvendig å gjøre justeringer av logo gjøres dette i løsningens CSS fil. Dette gjøres på følgende måte:

  1. Åpne filen ’BuddySamarbeidet.css’ i mappen BBWEB i en teksteditor, for eksempel Notepad.exe.
  2. Lengst opp i denne filen er det angitt hvilke parametere som kan endres for å tilpasse visningen av logo.
  3. Når det er gjort endringer i filen må den lagres.
  4. Når filen er lagret kontrollerer du på nytt hvordan logo vises ved å enten oppdatere en eksisterende kobling til løsningen eller ved å åpne adressen til løsningen i en internett browser.
  5. Dersom logo ser OK ut lukke CSS filen, hvis ikke gjøres flere tilpasninger til logo ser bra ut.

8 ENDRING AV TEKSTER

Enkelte tekster i løsningen er mulige å tilpasse.

Hovedtittelen til løsningen (vises til høyre for logo) kan endres ved å endre verdien for parameter med ID ’BUDDY-WEB-TITTEL’ i tabellen tblParams i databasen dbMetakatalog. Dersom det ikke gjøres noen endringer vil tittel feltet vise teksten ’Buddy Brukeradministrasjonsweb’.

Alle overskrifter som vises ved valg av funksjoner i meny, samt tekster i meny er mulig å endre ved å gjøre tilpasninger i tabellene tblWebSider og tblWebRettighetsKoder. Disse tekstene endres på følgende måte: 1. Start ’SQL Server Management Studio’ (SQL Server 2005) eller ’Query Analyzer’ (SQL Server 2003).

  1. Koble til databasen ’dbMetakatalog’.

  2. Åpne tabellen ’tblWebSider’ eller ’tblWebRettighetsKoder’.

  3. I tabellen ’tblWebSider’ kan teksten i feltet ’Navn’ endres. Dette vil påvirke tekstene som vises i meny, samt i overskrift og sidetittel.

  4. I tabellen ’tblWebRettighetskoder’ kan teksten i feltet ’Beskrivelse’ for alle funksjoner med verdi ’Vis menyelement’ endres. Dette vil påvirke teksten som vises under overskrift i siden når siden åpnes etter at den er valgt i menyen.

I enkelte websidene er det mulig å gjøre endringer direkte i HTML koden. HTML kode får du frem ved å åpne en av filene som har filendelsen ’.aspx’ i mappen ’BBWEB’ eller i mappen ’Secure’ i mappen ’BBWEB’. De websidene som det kan endres i er (mappe i parantes):

I filen ’Default.aspx’ (i mappen ’BBWEB’) bør det legges inne en tekst som forklarer at bruker må logge inn på løsningen for å kunne benytte funksjonaliteten i den. Alternativt så settes siden ’Logon.aspx’ som startside i egenskapene til web siden (i Internet Information Services (IIS) Manager i fanen ’Documents’).

I filen ’Forside.aspx’ (i mappen ’Secure’ i mappen ’BBWEB’) er det mulig å definere tekster som kan gjøres personlige. Dette gjøres ved å referere til det feltet i tabellen tblObjects i datbasen dbMetakatalog som inneholder den verdien som det er ønskelig å vise for den påloggede brukeren. For å referere til et felt så legges feltnavnet inn mellom [ ], for eksempel [DisplayName]. For eksempel dersom det er ønskelig å vise teksten ’Hei Ola!’ for en bruker som heter Ola så gjøres dette ved å legge inn teksten ’Hei [Firstname]!’ i kontroll med id ’headingLabel’. Dette gjelder for kontrollene med ID ’headingLabel’ og ’tekstLabel’.

9 VEDLEGG – EKSEMPEL WEB.CONFIG

<?xml version="1.0"?>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
<configSections>
    <sectionGroup name="system.web.extensions" type="System.Web.Configuration.SystemWebExtensionsSectionGroup, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
        <sectionGroup name="scripting" type="System.Web.Configuration.ScriptingSectionGroup, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
            <section name="scriptResourceHandler" type="System.Web.Configuration.ScriptingScriptResourceHandlerSection, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" requirePermission="false" allowDefinition="MachineToApplication"/>
            <sectionGroup name="webServices" type="System.Web.Configuration.ScriptingWebServicesSectionGroup, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
                <section name="jsonSerialization" type="System.Web.Configuration.ScriptingJsonSerializationSection, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" requirePermission="false" allowDefinition="Everywhere"/> 
                <section name="profileService" type="System.Web.Configuration.ScriptingProfileServiceSection, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" requirePermission="false" allowDefinition="MachineToApplication"/>
                <section name="authenticationService" type="System.Web.Configuration.ScriptingAuthenticationServiceSection, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" requirePermission="false" allowDefinition="MachineToApplication"/>
            </sectionGroup>
        </sectionGroup>
    </sectionGroup>
</configSections>
<system.web>
    <pages>
        <controls>
            <add tagPrefix="asp" namespace="System.Web.UI" assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
        </controls>
    </pages>
    <!--
      Set compilation debug="true" to insert debugging
      symbols into the compiled page. Because this
      affects performance, set this value to true only
      during development.
-->
    <compilation debug="true" defaultLanguage="c#">