OS2sofd
- Om OS2sofd: https://www.sofd.io/
- Brugervejledning: https://www.sofd.io/brugervejledning/
- Arkitektur: https://www.sofd.io/arkitektur/
- Implementeringsdrejebøger: https://www.sofd.io/implementation-guides/
- Drejebog: OPUS-kommune: https://www.sofd.io/implementation-guides/opus-loen-integration/
- Drejebog: SD-kommune: https://www.sofd.io/implementation-guides/sd-loen-integration/
- Brugerstyring: https://www.sofd.io/idm/
- Forudsætninger og forberedelse: https://www.sofd.io/idm/prerequisites/
- Processer og hændelser: https://www.sofd.io/idm/processes/
- Personinaktivering: https://www.sofd.io/idm/person-inactivation/
- Konfiguration: https://www.sofd.io/idm/configuration/
- Login og SAML: https://www.sofd.io/login/
- API: https://www.sofd.io/api/
- OData (læsning): https://www.sofd.io/api/odata/
- REST-API: https://www.sofd.io/api/rest/
- Fremtidig API-udvikling: https://www.sofd.io/api/strategi/
- Integrationer: https://www.sofd.io/integrationer/
- On-premise agenter: https://www.sofd.io/agents/
- Brugerkonto Agent: https://www.sofd.io/agents/user-account-agent/
- AD Writeback Agent: https://www.sofd.io/agents/ad-writeback-agent/
- AD Replikator Agent: https://www.sofd.io/agents/ad-replikator/
- AD indlæsningsintegration: https://www.sofd.io/agents/ad-indlaesningsintegration/
- OPUS indlæsningsintegration: https://www.sofd.io/agents/opus-indlaesningsintegration/
- Indlæsning af skoleelever: https://www.sofd.io/agents/skoleelev-indlaesning/
- OS2vikar - Brugerkonto Agent: https://www.sofd.io/agents/os2vikar-agent/
- Download: https://www.sofd.io/downloads/
- Ændringslog: https://www.sofd.io/changelog/
- Support og kontakt: https://www.sofd.io/support/
AD Writeback Agent holder attributter på eksisterende AD-brugerkonti opdateret med data fra SOFD Core (fx navn, titel og telefonnummer) ud fra en konfigurerbar feltmapning. Dette dokument beskriver installation og konfiguration.
| Komponent | Servicenavn | Download | Ændringslog |
| --- | --- | --- | --- |
| AD Writeback Agent | `SOFD Core AD Writeback Agent` | [Download](https://www.sofd.io/download/SOFD%20Core%20-%20AD%20Writeback%20Agent.exe) | [Ændringslog](#ændringslog) |
## Indledning
### Forudsætninger
#### Windows Server
Servicen skal installeres på en Windows maskine med:
- Netværksmæssig adgang til kommunens AD
- Netværksmæssig adgang til SOFD Core i skyen via HTTPS.
- .NET Framework 4.6.1 eller nyere
#### Service konto i AD
Der skal oprettes en service konto i kommunes AD.
Kontoen skal have skriveadgang til alle de bruger-attributter der skal opdateres fra SOFD Core, inkl CPR nummer attributten.
Bemærk at kontoen skal være medlem af Domain Admins hvis den skal kunne opdatere oplysninger på brugere som er eller har været medlem af en beskyttet gruppe (f.eks. andre domain admins).
En konto som "kun" er Account Operator kan ikke opdatere oplysninger på en bruger som har attributten AdminCount sat til 1.
#### API bruger til SOFD Core backend
Der skal i konfigurationen indtastes en API nøgle til SOFD Core. Denne kan oprettes i SOFD Cores administrative brugergrænseflade. Agenten kan nøjes med læseadgang.
## Installation af Windows Service
Der skal installeres og konfigureres en Windows Service på en server hvor der er netværksmæssig adgang til kommunens AD samt SOFD Core i skyen via HTTPS.
### Download service
Hent installeren via download-linket øverst på siden eller fra den samlede [Download-oversigt](../../downloads/).
### Konfiguration af service
Konfiguration af servicen foretages i applicationSettings sektionen i xml-filen **SOFD Core AD Writeback Agent.exe.config** som ligger i roden af installationsmappen (default C:\Program Files (x86)\Digital Identity\SofdCoreAdWritebackAgent).
| Indstilling | Eksempel | Kommentar |
|---|---|---|
| SofdUrl | https://kommune.sofd.io | Peger på SOFD installationen for kommunen |
| SofdApiKey | xxxxxx | Det kodeord som er valgt til klienten i SOFD |
| ActiveDirectoryWritebackIncludeOUs | OU=Kultur,OU=Administration,OU=Kommune,DC=digitalidentity,DC=dk; OU=IT og Digitalisering,OU=Administration,OU=Kommune,DC=digitalidentity,DC=dk | Begræns opdatering til brugere i disse OUer. Flere OUer kan angives adskilt med semikolon |
| ActiveDirectoryWritebackExcludeOUs | OU=Kultur,OU=Administration,OU=Kommune,DC=digitalidentity,DC=dk; OU=IT og Digitalisering,OU=Administration,OU=Kommune,DC=digitalidentity,DC=dk | Undtag opdatering af brugere i disse Ouer. Flere Ouer kan angives adskilt med semikolon. |
| ActiveDirectoryEnableManagerUpdate | False | Hvis True bliver "manager" attributten på brugernes AD-konti opdateret med lederen for den primære ansættelse i SOFD Core. |
| ActiveDirectoryManagerUpdateMasters | OPUS | Hvis angivet, vedligeholder agenten kun manager feltet på brugere som har en primær affiliation fra denne master. Flere værdier kan angives adskilt med semikolon. Kan anvendes hvis man f.eks. ikke ønsker at manager feltet skal udfyldes for eksterne brugere som er oprettet direkte via SOFD Core. |
| ActiveDirectoryManagerUpdateOnlyPrimes | True | Hvis denne er sat til true (default), bliver manager kun påført primære AD-konti. Ønskes manager også opdateret på øvrige konti, skal denne sættes til False |
| ActiveDirectoryManagerUpdateNoClear | False | Kun relevant hvis ActiveDirectoryEnableManagerUpdate er sat til true. Hvis denne sættes til true, bliver manager attributten ikke ryddet, selv om den burde blive det jf. data. |
| ActiveDirectoryManagerUpdateExcludedOrgunits | 10975924-bb05-4ac3-955d-91980d63b1d5; 26ceb852-b59f-4cda-8c49-cd5850abd3c5 | Semikolon-separeret liste af enhedsuuider. Tilhørsforhold i disse eller underliggende enheder bliver undtaget når der skal sættes manager attribut i AD. |
| ActiveDirectoryUserType | ACTIVE_DIRECTORY | Skal sættes til værdien "ACTIVE_DIRECTORY". Anvendes til at styre hvilke kontotyper der replikeres data fra. |
| ActiveDirectoryEnablePowershell | False | Hvis denne sættes til "True" afvikles et custom powershell script hver gang agenten laver en ændring på en bruger i AD. Script sti: ./CustomPowershell/UserChanged.psm1 |
| UploadConfiguration | False | Sæt "True" for at den lokale konfiguration bliver uploadet til SOFD Core |
| EnableFallbackToPrimeAffiliation | True | Default True. Sæt denne til False hvis der skal være en hård kobling til den ansættelse der er opmærket direkte på brugerkontoen. |
| FullSyncCron | 0 30 3 ? * * | Cron udtryk, der angiver hvornår der skal køres en fuld synkronisering. Default er hver nat kl. 03:30 som i eksemplet til venstre. |
| DryRunAttributes | False | Hvis "True" udføres en tør-kørsel, hvor agenten kun logger de attribut-ændringer den ville foretage, uden at skrive dem til AD. |
| CyberArkEnabled | False | Sættes til "True" for at hente SOFD API-nøglen fra CyberArk i stedet for direkte fra SofdApiKey. |
| CyberArkAPI | https://cyberark.kommune.dk | URL'en til kommunens CyberArk Web Service (CCP/AIM). Anvendes når CyberArkEnabled er "True". |
| CyberArkAppId | SOFDCore | App ID i CyberArk der anvendes ved opslag af SOFD API-nøglen. |
| CyberArkSafe | SOFD | Navnet på den safe i CyberArk hvor SOFD API-nøglen er gemt. |
| CyberArkObject | SofdApiKey | Navnet på det objekt i CyberArk safen der indeholder SOFD API-nøglen. |
### Start af service
Efter servicen er konfigureret startes den via Windows Services eller tilsvarende kommandolinjeværktøjer. Her er det vigtigt at servicen konfigureres til at starte med den AD konto som har de fornødne rettigheder.
## Konfiguration af attribute-opdatering
Konfigurationen af hvilke attributter der skal holdes opdateret hedder
ad-mapping.xml
Denne fil indeholder en konfiguration af hvilke felter fra SOFD der skal kopieres til hvilke felter i AD.
Der følger en eksempelfil med, som man bør tilrette. Eksempelfilen ser sådan her ud
```xml
```
For hver attribut fra SOFD man ønsker kopieret til en attribut i AD, skal der være en `` i filen. Denne peger på hhv en attribut i SOFD, og en attribut på bruger-objekterne i AD.
Attributnavnene i AD kan man finde i sit AD, og attributterne i SOFD kan man finde ved at lave API opslag i SOFD (det er API attribut-navnene der skal anvendes).
Digital Identity kan også hjælpe med udfyldelsen af filen.
Hvor der er flere mulige værdier i SOFD, vælges altid den primære at kopiere til AD. Fx den tredje mapping i eksempelfilen, hvor der står
```xml
```
En "affiliation" er et tilhørsforhold, og en medarbejder kan have flere tilhørsforhold (fx flere ansættelser). Når man laver en mapning på denne måde, så vælges det tilhørsforhold som er opmærket som det primære i SOFD.
"affiliation.orgUnit.ean" fortolkes som
- Vælg det primære tilhørsforhold for brugeren
- Find den enhed som tilhørsforholdet er knyttet til
- Udlæse EAN nummeret på den enhed
- Kopier værdien over i extensionattribute4 på bruger-objektet i AD
> [!NOTE]
> Bemærk det er kun muligt at kopiere enkelt-attributter **fra** SOFD Core **til** AD via denne mekanisme. Man kan ikke flette flere SOFD Core attributter og kopiere dem til ét felt i AD, og man kan ikke flette attributter fra SOFD Core med attributter i AD, og kopiere dem til et nyt felt i AD.
## Ændringslog
Ændringslog for AD Writeback Agent. Nyeste version øverst.
| Version | Dato | Ændring |
| --- | --- | --- |
| 2.47.0 | 08.05.2026 | Manager-attributten opdateres nu under delta-sync, og ændringer af enhedens leder udløser en fuld synkronisering (kræver OS2sofd 2026R1-build efter 8. maj) |
| 2.46.0 | 16.04.2026 | Tilføjet upper()- og lower()-funktioner til DSL, understøttelse af localExtensions på tilhørsforhold, samt en valgfri casing-parameter til validCN() |
| 2.45.0 | 09.04.2026 | Tilføjet professionName til tilhørsforholds-modellen og opdateret fallback-rækkefølgen for positionCalculatedName |
| 2.44.0 | 09.03.2026 | Tilføjet superiorLevel og subordinateLevel til tilhørsforholds-modellen |
| 2.43.0 | 27.01.2026 | Justeret xml-mapping-parseren |
| 2.43.0 | 21.01.2026 | Tilføjet validCN-syntaks til at understøtte cn med maks. 64 tegn |
| 2.42.0 | 28.11.2025 | Tilføjet sofdPaused xml-attribut samt understøttelse af LocalExtensions |
| 2.41.0 | 16.10.2025 | Ændret binding-indstillinger ved forbindelse til AD |
| 2.40.0 | 16.10.2025 | DefaultValue for tags kan nu være strengværdier |
| 2.39.0 | 15.09.2025 | Rettet logningsfejl ved manglende rettigheder til at opdatere AD |
| 2.38.1 | 12.06.2025 | Tilføjet phoneformat-metode |
| 2.38.0 | 11.06.2025 | Understøtter superiorLevel og subordinateLevel i writeback (kræver SOFD 2025R2) |
| 2.37.0 | 02.05.2025 | Understøttelse af searchWords i mappings |
| 2.36.1 | 09.05.2025 | Tilføjet indstillingen ActiveDirectoryWritebackIncludeOUs |
| 2.36.0 | 03.04.2025 | Dryrun-indstilling til attributter |
| 2.35.1 | 19.03.2025 | Flytter ikke længere deaktiverede brugere |
| 2.35.0 | 06.03.2025 | Kan nu flytte brugere til OU |
| 2.34.0 | 15.01.2025 | Tilføjet liste-mappings |
| 2.33.0 | 04.12.2024 | Tilføjet felterne calculatedFirstname og calculatedSurname |
| 2.32.0 | 15.10.2024 | Tilføjet vendor til tilhørsforholds-modellen |
| 2.31.0 | 23.08.2024 | Tilføjet understøttelse af inheritedEan-feltet |
| 2.30.0 | 01.08.2024 | Tilføjet understøttelse af CyberArk (Privileged Access Management) |
| 2.29.0 | 01.07.2024 | Tilføjet orgunit._X-syntaks til at gå X niveauer OP fra tilhørsforholdets ou-pointer, samt begrænsning af initialer til maks. 6 tegn |
| 2.28.0 | 19.06.2024 | Rettet fejl ved brug af indlejrede parent-org-udtryk i xml-mapping |
| 2.27.0 | 18.05.2024 | Understøtter positionShort fra OPUS |
| 2.26.0 | 12.04.2024 | Rydder ikke længere manager for brugere i ActiveDirectoryManagerUpdateExcludedOrgunits |
| 2.25.0 | 10.04.2024 | ActiveDirectoryManagerUpdateExcludedOrgunits udelukker nu også underenheder til den angivne enheds uuid |
| 2.24.0 | 19.02.2024 | Tilføjet parent-funktion til orgunit-mappings |
| 2.23.0 | 05.01.2024 | Tilføjet orgunit email, sd employeeId, homepage og authorizationcode til mappings |
| 2.22.0 | 04.01.2024 | Gjort fuld synkronisering konfigurerbar |
| 2.21.3 | 04.12.2023 | Tilføjet noget logning |
| 2.21.2 | 14.09.2023 | Rullet en tidligere rettelse tilbage (havde utilsigtede sideeffekter) |
| 2.21.1 | 13.09.2023 | Rettet fejl i tag-syntaksen |
| 2.21.0 | 30.08.2023 | Respekterer nu alternativ OrgUnit på tilhørsforhold |
| 2.20.0 | 01.08.2023 | Tilføjet kombitUuid til User |
| 2.19.0 | 26.06.2023 | Rettet mindre fejl i replace-logikken ved rydning af felter |
| 2.18.0 | 26.06.2023 | Tilføjet NOREPLACE-flag på AD-feltet for at undgå at overskrive værdier i AD |
| 2.17.0 | 22.06.2023 | Tilføjet ">"-operator i orgunit-mappings |
| 2.16.0 | 03.05.2023 | Rettet kompatibilitetsfejl med nyeste version af SOFD Core |
| 2.15.1 | 27.01.2023 | Fjernet standard-mapping der var tilføjet ved en fejl |
| 2.15.0 | 27.01.2023 | Kan nu udelukke enheder fra manager-opdatering |
| 2.14.0 | 09.01.2023 | Rettet fejl ved tildeling af lederes ledere |
| 2.13.0 | 12.12.2022 | Tilføjet personCalculatedName på person |
| 2.12.0 | 08.12.2022 | Tilføjet egenskaben opusEmployeeId på tilhørsforhold |
| 2.11.2 | 17.11.2022 | Tilføjet egenskaben phoneNumber45 på telefoner |
| 2.11.1 | 16.11.2022 | Rettet et par fejl ved mapping af enheders telefoner |
| 2.11.0 | 08.11.2022 | Tilføjet en trim()-metode |
| 2.10.1 | 07.11.2022 | Rettet null pointer-undtagelse i format()-metoden |
| 2.10.0 | 02.11.2022 | Tilføjet metoderne cprformat() og replace() |
| 2.9.1 | 24.10.2022 | Rettet en fejl i opususer-mapping når der ikke findes en opus-bruger |
| 2.9.0 | 21.10.2022 | Tilføjet pad()-metode til at udfylde felter med præfiks-tegn |
| 2.8.5 | 14.09.2022 | Rettet fejl ved rydning af manager-feltet når managerNoClear er sat til true |
| 2.8.4 | 07.09.2022 | Tilføjet felter for stillingens visningsnavn |
| 2.8.3 | 01.09.2022 | Tilføjet flere felter til "Felter.txt" |
| 2.8.2 | 25.08.2022 | Writeback bruger nu enhedens displayName hvis den findes |
| 2.8.1 | 15.06.2022 | Telefoner sorteres nu korrekt efter type-prime i stedet for prime |
| 2.8.0 | 10.05.2022 | Kan nu konfigurere manager-opdatering med NoClear-indstilling, så manager-attributten ikke ryddes |
| 2.7.3 | 01.03.2022 | Join-udtryk evalueres nu til null, hvis en af join-parametrene er null. |
| 2.7.2 | 21.02.2022 | Rettet offset-fejl i deltasync |
| 2.7.1 | 30.01.2022 | Rettet feltnavne på orgunit |
| 2.7.0 | 28.01.2022 | Tilføjet flere navnefelter til OrgUnit |
| 2.6.4 | 27.01.2022 | Custom PowerShell indlæses nu kun ved behov |
| 2.6.3 | 21.01.2022 | Tilføjet join-metode til DSL. Tilføjet mulighed for at slå fallback til primært tilhørsforhold fra. |
| 2.6.2 | 18.01.2022 | Manager-opdatering understøtter nu mapping via brugerens employee_id |
| 2.6.1 | 05.01.2022 | Mindre fejlrettelser i kald af custom PowerShell |
| 2.6.0 | 28.12.2021 | Understøttelse af kald af custom PowerShell-script efter en bruger er ændret i AD |
| 2.5.0 | 22.12.2021 | Understøttelse af den nye substitute (vikar) affiliationType (kræves for at bruge vikar-modulet i SOFD Core) |
| 2.4.0 | 18.10.2021 | Understøtter EmployeeID-reference på User-objekter til mapping af tilhørsforholdsdata (fallback til primært tilhørsforhold uden mapping) |
| 2.3.0 | 10.06.2021 | Understøtter et NOCLEAR-flag på AD-feltet, så feltet ikke ryddes hvis data ikke længere findes i SOFD |
| 2.2.1 | 07.06.2021 | Tilføjet rettelser til versionering |
| 2.2.0 | 03.06.2021 | Tillader mapping af felter fra User-objektet i SOFD til det tilsvarende User-objekt i AD (fx employeeId) |
| 2.1.2 | 20.05.2021 | Rettet fejl i ^-DSL-syntaksen |
| 2.1.1 | 19.05.2021 | Tilføjet isnull-metode til writeback-DSL. |
| 2.1.0 | 19.05.2021 | Understøtter TLS 1.2 |
| 2.0.0 | 19.04.2021 | Udskilt Writeback Agent som selvstændigt modul |
| 1.6.8 | 25.03.2021 | Tilføjet prefix-metode til writeback-DSL. |
| 1.6.7 | 23.03.2021 | Rettet fejl i OU-udelukkelse. Tilføjet master-filter for Manager. |
| 1.6.6 | 19.03.2021 | Rettet Manager-fejl. Tilføjet OU-udelukkelseskonfiguration til writeback. |
| 1.6.5 | 15.03.2021 | Rettet fejl i tag-DSL |
| 1.6.4 | 12.03.2021 | Rettet fejl ved kald af DeactivateExchange-PowerShell |
| 1.6.3 | 10.03.2021 | Tilføjet static-metode til writeback-DSL. Tilføjet håndtering af accountExpires i writeback |
| 1.6.2 | 05.03.2021 | Tilføjet understøttelse af telefontyper. Tilføjet left- og right-funktion til writeback-DSL |
| 1.6.1 | 24.02.2021 | Rettet NPE-undtagelse når brugeren ikke har et primært tilhørsforhold. Fjernet kravet om ExchangeServer-egenskaben når der køres med ExchangeOnlyPowershell=true. |
| 1.6.0 | 22.02.2021 | Understøttelse af kun at køre PowerShell ved oprettelse/sletning i Exchange |
| 1.5.4 | 04.02.2021 | Rettet nedarvningsfejl i tag-mapping |
| 1.5.3 | 02.02.2021 | Rettet fejl ved skrivning af samme sofd-værdi til flere AD-attributter. Tilføjet understøttelse af tags ved skrivning til AD-attributter. |
| 1.5.2 | 14.12.2020 | Rettet fejl i ExchangeService, der gjorde at PowerShell-sessioner ikke blev frigivet korrekt |
| 1.5.1 | 11.12.2020 | Understøttelse af unilogin-mapping i writeback |
| 1.5.0 | 10.11.2020 | Understøtter vedligehold af AD'ets manager-attribut |
| 1.4.1 | 21.10.2020 | Understøtter concat() til attribut-writeback |
| 1.4.0 | 29.09.2020 | Implementering af ny navnestandard (kræver at SOFD Core også opdateres) |
| 1.3.6 | 28.09.2020 | Tilføjet quickfix til EmployeeID-matchningsproblem ved genaktivering af AD-konti |
| 1.3.5 | 03.09.2020 | Skiftet til 64bit. Kan nu bruge PSSnapin ved forbindelse til Exchange. |
| 1.3.4 | 28.08.2020 | Yderligere logning når brugernavn ikke kan genereres |
| 1.3.3 | 27.08.2020 | Fejlrettelse til e-mailadressen i OPUS-mailudsendelse |
| 1.3.2 | 14.08.2020 | Rettet PowerShell-pipeline-fejl ved oprettelse af Exchange-postkasse |
| 1.3.1 | 07.08.2020 | Sætter Alias og EmailPolicy ved aktivering af remote-postkasse |
| 1.3.0 | 06.08.2020 | Quickfixes til brugernavnsgenerering for Exchange og OPUS (midlertidigt, indtil en langsigtet løsning laves) |
| 1.2.4 | 04.08.2020 | Sender EmailAlias til Exchange-PowerShell-scripts |
| 1.2.3 | 24.07.2020 | Understøtter alle telefontyper |
| 1.2.2 | 30.06.2020 | Understøtter konti med bindestreg-CPR ved genaktivering |
| 1.2.1 | 25.06.2020 | Rettet fejl i den nye brugernavnsgenerator |
| 1.2.0 | 12.06.2020 | Understøtter userIds med fast længde |
| 1.1.0 | 22.04.2020 | Tillader upload af den lokale konfiguration til SOFD Core |
| 1.0.4 | 03.04.2020 | Ændret adfærd for EmployeeID-feltet, så det også kan sættes i ikke-singleUser-tilfælde |
| 1.0.3 | 02.04.2020 | Rettet tastefejl i logbesked, og rettet mappe-placering af ad-mapping.xml |
| 1.0.2 | 29.03.2020 | Tilføjet -Confirm:$false til Disable-Mailbox-kommandoer for Exchange |
| 1.0.1 | 28.03.2020 | Tilføjet genereret userId til statusbeskeden i SOFD Core GUI; rettet fejl i Attribute Writeback, der forårsagede en FULD synkronisering hvert 5. minut |
| 1.0.0 | 26.03.2020 | Opdateret med rettelse for userTypes |