Spesifikasjon av Cerebrums API mot Exchange

1.1   Kommandoers omslag

Alle kommandoer beskrevet nedenfor utføres gjennom å kalle opp powershell.exe-fil på springbrettmaskinen med predefinerte parametere og passere selve kommandoen som en parameter også. Dette ser sånn ut:

%SystemRoot%\syswow64\WindowsPowerShell\v1.0\powershell.exe
-NonInteractive -NoLogo -NoProfile -Command "<koden>"

Kommandoene i tillegg må også kjøres i en spesiell sesjon som åpnes mot management serveren. I praksis betyr det at <koden> over inneholder ikke bare selve kommandoen, men også tilleggskode før og etter kommandoen, som sjekker om det finnes en åpen sesjon mot management serveren, åpner den om nødvendig og kobler til og fra sesjonen. Hele <koden> for å kjøre, for eksempel whoami kommando, vil se sånn ut:

$pass = ConvertTo-SecureString -Force -AsPlainText %(ex_pasw)s;
$cred = New-Object System.Management.Automation.PSCredential(%(ex_domain_user)s, $pass);

$sessions = Get-PSSession -ComputerName %(management_server)s -Credential $cred -Name %(session_key)s 2> $null;

if ( $sessions ) {
    $ses = $sessions[0];
    Connect-PSSession -Session $ses 2> $null > $null;
}

if (($? -and ! $ses) -or ! $?) {
    $ses = New-PSSession -ComputerName %(management_server)s -Credential $cred -Name %(session_key)s;

    Import-Module ActiveDirectory 2> $null > $null;
    Invoke-Command { . RemoteExchange.ps1 } -Session $ses;

    Invoke-Command { $pass = ConvertTo-SecureString -Force -AsPlainText %(ex_pasw)s } -Session $ses;

    Invoke-Command { $cred = New-Object System.Management.Automation.PSCredential(%(ex_user)s, $pass) } -Session $ses;

    Invoke-Command { $ad_pass = ConvertTo-SecureString -Force -AsPlainText %(ad_pasw)s } -Session $ses;

    Invoke-Command { $ad_cred = New-Object System.Management.Automation.PSCredential(%(ad_domain_user)s, $ad_pass) } -Session $ses;

    Invoke-Command { Import-Module ActiveDirectory } -Session $ses;

    Invoke-Command { function get-credential () { return $cred;} } -Session $ses;

    Invoke-Command { Connect-ExchangeServer -ServerFqdn %(management_server)s -UserName %(ex_user)s } -Session $ses;
}
write-output EOB;

Invoke-Command {whoami} -Session $ses;

Disconnect-PSSession $ses 2> $null > $null;

Variablene i denne kodeblokka:

%(ex_pasw)s

Passordet til brukeren som er exchange-administrator.

%(ex_domain_user)s

Navnet til brukeren som er exchange-administrator.

%(management_server)s

Navnet til management server.

%(session_key)s

En unik identifikator som utgjøres ut av PID til prosessen som åpner en ny sesjon mot management server og brukes videre for å identifisere denne sesjonen.

%(ad_pasw)s

Passordet til brukeren som er administratoren til AD-domenet.

%(ad_domain_user)s

Navnet til brukeren som er administratoren til AD-domenet.

Å kjøre hvilken som helst kommando beskrevet nedenfor betyr i praksis å sette tilsvarende kode istedenfor whoami i kodeblokka over.

1.2   new_mailbox

Funksjonen oppretter en ny postboks for en bruker i Exchange, og skjuler den fra visning.

Kommandoen som kjøres:

New-MailBox -alias $username `
            -name $username `
            -DisplayName $fullname `
            -LinkedDomainController $adserver `
            -LinkedMasterAccount $domain\$username `
            -LinkedCredential $ad_cred `
            # Eventuelt også, hvis definert:
            -FirstName $firstname `
            -LastName $lastname `
            -Database $maildatabase `
            -OrganizationalUnit $ou `
            ; `
Set-Mailbox -Identity $username
            -HiddenFromAddressListsEnabled $true

En del av variablene blir satt ut fra informasjon i Cerebrum.

Visningsskjulingen gjøres direkte for å beskytte postbokser som ikke skal være synlige og korte ned perioden der postboksen er synlig. Visningen kan deretter åpnes opp av en annen kommando etterpå.

1.3   set_primary_mailbox_address

Funksjonen setter primær e-postadresse for en postboks.

Kommandoen som kjøres:

Set-Mailbox -Identity $username -PrimarySmtpAddress $address

Det har blitt vurdert å samtidig sette EmailAddressPolicyEnabled, men det blir ikkje satt per idag.

1.4   add_mailbox_addresses

Funksjonen legger til en e-postadresse til ein postboks.

Kommandoen som kjøres:

Set-Mailbox -Identity $username -EmailAddresses @{'add'=$addresses}

der $addresses er en liste over alle e-postadressene til brukeren.

1.5   remove_mailbox_addresses

Funksjonen fjerner e-postadresser fra en postboks.

Kommandoen som kjøres:

Set-Mailbox -Identity $username -EmailAddresses @{'remove'=$addresses}

der $addresses er en liste over e-postadressene som skal slettes.

1.6   set_mailbox_visibility

Funksjonen setter synligheten til postboksen av eller på.

Dette kan brukes til å for eksempel bare gjøre primærbrukere synlige, eller ta hensyns til reservasjonsinnstillinger registrert i SAP og/eller FS.

Kommandoen som kjøres:

Set-Mailbox -Identity $username -HiddenFromAddressListsEnabled $hidden

der $hidden er en boolsk variabel.

1.7   set_mailbox_address_policy

Funksjonen setter postboksen til policy-enabled eller -disabled.

Kommandoen som kjøres:

Set-Mailbox -Identity $username -EmailAddressPolicyEnabled $policy

der $policy er en boolsk variabel.

1.8   set_mailbox_singleitemrecovery

Funksjonen setter SingleItemRecoveryEnabled for en postboks.

Kommandoen som kjøres:

Set-Mailbox -Identity $username -SingleItemRecoveryEnabled $policy

der $policy er en boolsk variabel.

1.9   set_mailbox_quota

Funksjonen setter kvote på postboksen.

Det er ønskelig å sette en kontos kvote for eksempel når en person blir ansatt, i stedet for å være student.

Kommandoen som kjøres:

Set-Mailbox -Identity $username `
            -IssueWarningQuota '$soft MB' `
            -ProhibitSendReceiveQuota '$hard MB' `
            -ProhibitSendQuota '$hard MB' `
            -UseDatabaseQuotaDefaults:$false

der $soft og $hard er nummerverdier for kvoten som er satt på gitt MailTarget i Cerebrum.

1.10   set_mailbox_names

Funksjonen setter navnet på brukeren.

Merk at brukeren her er en "skyggebruker" som befinner seg i ressursdomenet Exchange kjører i, og ikkje brukeren fra hoveddomenet som postboksen er linket til (skyggebrukeren har samme navn som brukeren fra hoveddomene).

Kommandoen som kjøres:

Set-User -Identity $username `
         -Firstname $firstname `
         -LastName $last_name `
         -DisplayName $fullname

1.11   export_mailbox

Dette er ikke implementert.

1.12   remove_mailbox

Funksjonen fjerner postboksen og den linkede brukeren fra Exchange.

Merk: Denne kommandoen/funksjonaliteten kjøres ikke per i dag, da det ikke er blitt avklart hva som skal gjøres med gjenopprettinger.

Kommandoen som kjøres:

Remove-Mailbox -Identity $username `
               -Confirm:$false

Exchange vil, når denne kommandoen kjøres, arkivere postboksen i en definert periode. Cerebrum vil etter dette ikke kunne få tak i postboksen, gjenoppretting må gjøres på Exchange-siden. Arkivering kan gjøres med kommandoen New-MailboxExportRequest.

På UiO er det meningen at postboksen skal arkiveres i en PST-fil på et Samba-share. Det er mulig å implementere gjenoppretting av postbokser fra PST-filer via Cerebrum. Antallet gjennopprettinger tenderer til å være lavt på UiO, derfor håndteres dette manuelt fra Exchange-siden, da en implementasjon vil være kostbar både teknisk og policymessig.

1.13   set_forward

Funksjonen setter en videresendingsadresse for postboksen.

Merk: Det er bare støtte for å sette en forward-adresse for en postboks.

Kommandoen som kjøres:

Set-Mailbox -Identity $username `
            -ForwardingSmtpAddress $address

der $address er en gyldig e-postadresse. For å slå av videresending settes parameteret til $null.

1.14   set_local_delivery

Funksjonen setter opp om postboksen skal ha lokal levering av e-post, altså om innkommende e-post skal legges i postboksen i tillegg til å sendes til videresendingsadressen.

Kommandoen som kjøres:

Set-Mailbox -Identity $username `
            -DeliverToMailboxAndForward $local

der $local er en boolsk variabel.

1.15   new_group

Funksjonen oppretter en mail enabled security group.

Kommandoen som kjøres:

New-ADGroup -Name $groupname `
            -GroupCategory Security `
            -GroupScope Universal `
            -Server $resource_ad_server `
            # Eventuelt også:
            -Path $ou `
            ; `
Enable-Distributiongroup -Identity CN=$gname,$ou `
                         -DomainController $resource_ad_server `
                         -Confirm:$false

1.16   new_roomlist

Funksjonen oppretter en romliste, som er en distribusjonsgruppe.

Kommandoen som kjøres:

New-DistributionGroup -Name $groupname `
                      -Type Distribution `
                      -GroupCategory Security `
                      -OrganizationalUnit $ou `
                      -RoomList `
                      -Confirm:$false

1.17   remove_roomlist

Funksjonen fjerner en romliste.

Kommandoen som kjøres:

Remove-DistributionGroup -Identity $groupname `
                         -Confirm:$false

1.18   remove_group

Funksjonen fjerner en mail enabled security group.

Kommandoen som kjøres:

Remove-ADGroup -Identity $groupname `
               -Confirm:$false

1.19   set_group_display_name

Funksjonen setter DisplayName på en Exchange-gruppe.

Merk: Dette oppdaterer grupper som er i ressurs-domenet som Exchange ligger i. Hoveddomenet, uio.no, blir oppdatert gjennom en egen integrasjon - den vanlige AD-synken.

Kommandoen som kjøres:

Set-ADGroup -Identity $groupname `
            -DisplayName $dn

1.20   set_distgroup_description

Funksjonen setter Description på en distribusjonsgruppe.

Kommandoen som kjøres:

Set-Group -Identity $groupname `
          -Notes $description

1.21   set_distgroup_address_policy

Funksjonen setter AddressPolicy av eller på for en distribusjonsgruppe.

Kommandoen som kjøres:

Set-DistributionGroup -Identity $groupname `
                      -EmailAddressPolicyEnabled $enabled

1.22   set_distgroup_primary_address

Funksjonen setter primæradressen til en distribusjonsgruppe.

Kommandoen som kjøres:

Set-DistributionGroup -Identity $groupname `
                      -PrimarySmtpAddress $address

1.23   set_distgroup_visibility

Funksjonen setter synligheten til en distribusjonsgruppe i adresseboken.

Kommandoen som kjøres:

Set-DistributionGroup -Identity $groupname `
                      -HiddenFromAddressListsEnabled $visible

1.24   add_distgroup_addresses

Funksjonen legger til adresser for en distribusjonsgruppe.

Kommandoen som kjøres:

Set-DistributionGroup -Identity $groupname `
                      -EmailAddresses @{'add'=$addresses}

1.25   add_distgroup_member

Funksjonen legger til medlemmer i en distribusjonsgruppe.

Kommandoen som kjøres:

Add-DistributionGroupMember -Identity $groupname `
                            -Member $member
                            -BypassSecurityGroupManagerCheck

Kommandoen håndterer tilbakemeldinger/feilmeldinger fra Exchange om at adressen allerede er lagt til i gruppen (MemberAlreadyExistsException fra powershell), og anser jobben da som utført.

1.26   remove_distgroup_member

Funksjonen fjerner medlemmer fra en distribusjonsgruppe.

Kommandoen som kjøres:

Remove-DistributionGroupMember -Identity $groupname `
                               -Member $members
                               -BypassSecurityGroupManagerCheck
                               -Confirm:$false

1.27   remove_distgroup_addresses

Funksjonen fjerner adresser fra en distribusjonsgruppe.

Kommandoen som kjøres:

Set-DistributionGroup -Identity $groupname `
                      -EmailAddresses @{'remove'=$addresses}

1.28   set_distgroup_member_restrictions

Funksjonen setter inn- og utmeldingsregler på en distribusjonsgruppe.

Kommandoen som kjøres:

Set-DistributionGroup -Identity $groupname `
                      -MemberJoinRestriction $joins
                      -MemberDepartRestriction $parts

der $joins og $parts er valgfrie.

1.29   set_distgroup_manager

Funksjonen setter administrator-adressen for en distribusjonsgruppe.

Kommandoen som kjøres:

Set-DistributionGroup -Identity $groupname `
                      -ManagedBy $address
                      -BypassSecurityGroupManagerCheck

1.30   Funksjonalitet det ikke er støtte for

Noe funksjonalitet har det ikke vært behov for, og vi har derfor ikke noe funksjonalitet for det:

• Flytting av postbokser. Cerebrum har ikke lenger begrep om mail-databaser, men lar det være opp til Exchange å selv administrere.
• Arkivering og sletting av postbokser. Dette håndteres på Exchange-siden og ikke av Cerebrum.
• Funksjonalitet for å sette ModeratedBy og ModerationEnabled har blitt fjernet fra integrasjonen.

2.1   Oppretting av postboks

Dette vil skje for hendelser av typen spread:add, som betyr at en entitet har fått et spread. Alle andre spreads enn account@exchange blir ignorert.

Videre kommer en kort forklaring på hva som skjer, i grove trekk. Merk at nesten hver handling i opprettelsesprosessen oppdaterer en event, slik at om noe skulle feile vil det bli prøvd på nytt etterpå.

• Postboksen opprettes, se new_mailbox. Det logges en event om at postboksen har blitt opprettet, exchange:acc_mbox_create, som kan føre til andre handlinger etterpå.
• Adresse-policy settes til False, se set_mailbox_address_policy.
• Singleitemrecovery settes til True, se set_mailbox_singleitemrecovery.
• Visning oppdateres for postboksen, se set_mailbox_visibility. Skjules bare om personen er reservert fra publisering.
• E-postadressene legges til, se add_mailbox_addresses.
• Primær e-postadresse settes, se set_primary_mailbox_address.
• Kvoter settes, se set_mailbox_quota.
• Det genereres events for å trigge gruppeinnmelding i Exchange, basert på eksisterende gruppemedlemskap. Dette er for å sikre seg at brukeren blir med i riktige grupper i Exchange fra starten av.
• Videresendingsadresse settes dersom det er registrert for brukeren, se set_forward.
• Lokal levering settes dersom det er registrert for brukeren, se set_local_delivery.

Eventer som er blitt opprettet under opprettingen vil bli videre behandlet av eventmotoren etterpå.

2.2   Fjerning av postboks

Dette vil skje for hendelser av typen spread:remove, som betyr at en entitet har mistet et spread. Alle andre spreads enn account@exchange blir ignorert.

Denne handlingen vil avslutte uten å gjøre noe, da dette ikke skal gjøres av eventmotoren, men administreres i Exchange i steden for.

2.3   Oppdatering av navn

Dette vil skje for hendelser av typene:

• person_name:add
• person_name:remove
• person_name:modify

For hver brukerkonto som tilhører personen og som har spread account@exchange vil navnet bli forsøkt oppdatert. Se set_mailbox_names.

2.4   Oppdatering av synlighet

Dette vil skje for hendelser av typene:

• entity_trait:add
• entity_trait:modify
• entity_trait:remove
• group_member:add
• group_member:remove
• account_type:add (for å håndtere bytte av primærkonto)
• account_type:modify (for å håndtere bytte av primærkonto)
• account_type:remove (for å håndtere bytte av primærkonto)

Dette kommer av reservasjoner fra SAP og FS er representert av gruppemedlemskap i reservasjonsgruppene SAP-reservasjoner, FS-aktivt-samtykke og nå også randsone-aktivt-samtykke.

For hver brukerkonto som tilhører personen og som har spread account@exchange vil synligheten bli forsøkt satt, basert på registreringene på personen i Cerebrum. Logikken her er komplisert, og overstyres noe i Exchange-integrasjonen:

1. Hvis personen er med i gruppen randsone-aktivt-samtykke vil personen bli gjort synlig. Dette overstyrer den vanlige tolkningen av å være reservert fra publisering i Cerebrum.
2. Ellers blir personen gjort synlig ved å følge standard algoritme for å vurdere publisering i Cerebrum, basert på informasjon frå SAPUiO og FS.

Merk at det er bare primærbrukeren til personen som blir publisert. Alle andre brukerkontoer blir skjulte.

Se set_mailbox_visibility for hvordan det settes i Exchange.

2.5   Oppdatering av kvoter

Dette vil skje for hendelser av typene:

• email_quota:add
• email_quota:modify
• email_quota:remove

Kvoten settes, se set_mailbox_quota.

2.6   Oppdatering av videresendingsadresse

Dette vil skje for hendelser av typene:

• email_forward:add
• email_forward:remove
• email_forward:enable
• email_forward:disable

Lokal levering settes ikke her, men i Oppdatering av lokal levering.

Se set_forward for hvordan Exchange oppdateres.

2.7   Oppdatering av lokal levering

Dette vil skje for hendelser av typene:

• email_forward:add
• email_forward:remove
• email_forward:enable
• email_forward:disable

Dersom videresendingsadressen ikke er til en av brukerene sine egne adresser blir hendelsen ignorert, da den behandles i Oppdatering av videresendingsadresse.

Se set_local_delivery for hvordan Exchange oppdateres.

2.8   Legge til e-postadresse

Dette vil skje for hendelser av typen email_address:add.

Adressen settes, se add_mailbox_addresses.

2.9   Fjerne e-postadresse

Dette vil skje for hendelsen email_address:remove.

Adressen fjernes, se remove_mailbox_addresses

2.10   Oppdatering av primæradresse

Dette vil skje for hendelser av typen:

• email_primary_address:add
• email_primary_address:modify
• email_primary_address:remove

Addressen vil bli oppdatert, se set_primary_mailbox_address.

2.11   Oppretting av grupper

Dette vil skje for hendelsen spread:add for spread group@exchange. Grupper kan både være vanlige distribusjonsgrupper og romlister.

1. Gruppen eller romlisten opprettes, se hhv. new_group eller new_roomlist.

2. AddressPolicy settes for gruppen, se set_distgroup_address_policy.

3. Om gruppen er en vanlig distribusjonsgruppe og ikke en romliste:

   • Primæradressen settes, se set_distgroup_primary_address.
   • Andre adresser legges til, se add_distgroup_addresses.
   • Visibility settes, se set_distgroup_visibility.
   • Moderator-adresse settes, se `set_distgroup_moderator`_.
   • Gruppen settes til å være moderert dersom den skal være det, se `set_distgroup_moderation`_.

4. Manager-adresse, DisplayName og Description settes, se set_distgroup_manager, set_group_display_name og set_distgroup_description.

5. En hendelse for å legge til hvert medlem lages, og hendelsene prosesseres for seg etterpå.

2.12   Fjerning av grupper

Dette vil skje for hendelsen dlgroup:delete. Grupper kan både være vanlige distribusjonsgrupper og romlister.

Distributionsgruppen eller romlisten fjernes, se hhv. remove_group og remove_roomlist.

2.13   Legge til gruppemedlemmer

Dette vil skje for hendelsen group_member:add, for gruppper med Exchange-spread.

Medlemmet som er innmeldt meldes inn i gruppen, se add_distgroup_member. Dersom medlemmet er av entitetstypen person meldes primærbrukeren inn i gruppen. Brukere uten Exchange-spread blir ignorerte.

Dersom gruppenavnet har en konfigurerbar prefiks, vil brukeren også meldes inn i alle foreldregrupper av den gitte gruppen. Dette brukes for å få de automatiske ansatt-gruppene til å passe med Exchange sin behandling av gruppene.

2.14   Fjerne gruppemedlemmer

Dette vil skje for hendelsen group_member:remove, for gruppper med Exchange-spread.

Medlemmet som ble utmeldt i Cerebrum meldes ut av gruppen i Exchange, se remove_distgroup_member. Dersom medlemmet er av entitetstypen person meldes primærbrukeren ut av gruppen. Brukere uten Exchange-spread blir ignorerte.

Dersom gruppenavnet har en konfigurerbar prefiks, vil brukeren også meldes ut av alle foreldregrupper av den gitte gruppen. Dette brukes for å få fjernet brukeren fra de automatiske ansatt-gruppene i Exchange, siden brukeren meldes inn i alle foreldregruppene i strukturen.

2.15   Oppdatering av gruppe-synlighet

Dette vil skje for hendelsen dlgroup_hidden:modify, for grupper med Exchange-spread.

Gruppen sin synlighet oppdateres i Exchange, se set_distgroup_visibility.

2.16   Oppdatering av Item Recovery

Denne hendelsen er ikke støttet.

2.17   Oppdatering av adressepolicy

Dette vil skje for hendelsen exchange_ea_policy:set.

Dersom policyen er blitt endret for en bruker, se set_mailbox_address_policy, for grupper se set_distgroup_address_policy.

2.18   Oppdatering av manager

Dette vil skje for hendelsen dlgroup_manager:set, som betyr at noen har endret administreringsadressen til gruppen i Cerebrum.

Den nye satte manager-adressen oppdateres i Exchagen, se set_distgroup_manager.

2.19   Oppdatering av moderator

Dette vil ikke skje for noen hendelse.

Skjedde tidligere for hendelsen dlgroup:modmodby, som betyr at noen har endret moderatoradressen til gruppen i Cerebrum.

Den nye moderator-adressen oppdateres i Exchange, se `set_distgroup_moderator`_.

2.20   Oppdatering av moderering

Dette vil ikke skje for noen hendelse.

Skjedde tidligere for hendelsen dlgroup:modenable, som betyr at noen har slått av eller på moderering av gruppen.

Modereringsvalget sendes til Exchange, se `set_distgroup_moderation`_.

2.21   Oppdatering av inn- og utmeldingsregler for distribusjonsgrupper

Dette vil ikke skje for noen hendelse.

Skjedde tidligere for hendelsene dlgroup:moddepres og dlgroup:modjoinre.

Reglene som ble satt blir sendt til Exchange, se set_distgroup_member_restrictions.

2.22   Oppdatering av DisplayName og Description for grupper

Dette vil skje for hendelsene entity_name:add, entity_name:modify og entity_name:remove, for grupper med Exchange-spread.

DisplayName hentes ut fra navnetabellen, med bokmål som standard språk, og oppdateres i Exchange med set_group_display_name. Description hentes ut fra gruppen sitt vanlige description-felt i Cerebrum og oppdateres i Exchange med set_distgroup_description.