In sieben Schritten GINA-User aus Kundendaten erzeugen

Unsere GINA-Technologie ermöglicht es, auch mit denjenigen Empfängern verschlüsselt per E-Mail zu kommunizieren, die keine eigene Verschlüsselungstechnologie im Einsatz haben. Um für Empfänger, die nur selten verschlüsselte E-Mails lesen, den Prozess weiter zu vereinfachen, entstand der Wunsch, GINA-Konten vorab anlegen zu können. Das ergibt vor allem dann Sinn, wenn verschlüsselte Daten an eine Vielzahl von Empfängern gesendet werden und das entsprechende Passwort den Empfängern bekannt sowie in irgendeiner Form beim Versender verfügbar ist, beispielsweise die letzte Rechnungsnummer, Sozialversicherungs- oder Kundennummer etc. Damit lassen sich große Mengen an GINA-Usern anlegen und stetig aktualisieren. Zur Bewältigung dieser Aufgabe haben wir eine Legacy API entwickelt, die zwar nicht offiziell unterstützt wird, aber dennoch gut funktioniert. Rund um diese REST API gibt es ein PowerShell-Modul, mit dem sich die API ansteuern lässt. Das PowerShell-Modul ist plattformunabhängig, sodass es unter Windows, Linux und macOS verwendet werden kann, und unterstützt Windows PowerShell 5.1 bis PowerShell 7. Wie eine solche Benutzeranlage in der Praxis aussieht, wird nachfolgend dargestellt.

Legacy API einrichten

Die Legacy API wird standardmäßig ab Version 11.1.9 ausgeliefert. Um die API zu nutzen, muss man eine Gruppe „legacyappadmin“ erstellen und einen Benutzer zu dieser Gruppe hinzufügen, der dann Zugriff auf die API hat. Für diese Zwecke empfehlen wir, einen eigenen Benutzer anzulegen, der ansonsten keine Admin-Rechte besitzt. Dieser Benutzer benötigt keine encrypt/sign-Lizenz.

PowerShell-Modul installieren

Das PowerShell-Modul ist auf dem öffentlichen PowerShell Repository von Microsoft verfügbar und kann von dort mittels „Install-Module SEPPmailLegacy – Scope CurrentUser -AllowPrerelease“ installiert werden. Dies ist von Windows, Linux oder macOS möglich.

Das Legacy-API Modul ist derzeit noch in einer Prerelease Version verfügbar. Ab Version 1.0 muss man bei der Installation den „-AllowPrerelease“ Parameter weglassen.

Um eine Installation durchzuführen, muss die Execution Policy zumindest auf „RemoteSigned“ gesetzt werden (als Administrator: Set-ExecutionPolicy RemoteSigned).

Falls die Installationen von der Powershell Gallery im Unternehmen nicht erlaubt sind, stehen in der Readme-Datei auf GitHub alternative Installationswege beschrieben.

Konfiguration erzeugen

Wenn man das Modul erstmalig mit „Import-Module SEPPmailLegacy“ lädt, wird man dazu aufgefordert, eine neue Konfiguration zu erstellen. Die Konfiguration enthält Zugangsinformationen zu einer einzelnen SEPPmail-Appliance. Die Anlage erfolgt zum Beispiel mittels New-SLConfig -SEPPmailFQDN securemail.contoso.de -UserName LegacyAPIUser.

Die Konfiguration wird als Datei im Home-Verzeichnis, Unterordner „.SEPPmailLegacy“ abgespeichert.

Falls bei der Anlage etwas falsch eingegeben wurde, kann sie mittels „Remove-SLConfig“ gelöscht und danach neu angelegt werden.

Eine neu angelegte Konfiguration wird sofort als Standardkonfiguration festgelegt und lässt sich mittels „Test-SLConfig“ überprüfen.

Daten aufbereiten

Über die Kommandozeile können GINA-User nun einzeln erzeugt werden.

Beispiel:

New-SLGinaUser -eMailAddress max.mustermann@contoso.de -userName MaxMustermann -pwd Abc123!

Wie die Beispiele auf GitHub zeigen, können anschließend beliebig viele Benutzer erzeugt werden.

userName

eMailAdress

mobile

password

Alice Miller

alice.miller@contoso.com

+436684203731

Abc123

Bob Brown

bob.brown@contoso.com

+4366087654312

Cde456

Charly White

charly.white@contoso.com

+436769876223

Fgh481$

GINA-User anlegen

Nachdem alle Vorbereitungen getroffen wurden, ist es möglich, die CSV-Dateien direkt zu verwenden, um GINA-User anzulegen.

Import-Csv \NewGINAUsers.csv|New-SLGINAUser

Damit werden alle GINA-Benutzer aus der CSV-Datei erzeugt.

GINA-User aktualisieren

Bestimmte Anwendungsszenarien können es erfordern, dass gewisse GINA-Daten regelmäßig zu aktualisieren sind. Wenn etwa beim Versand von Rechnungen das GINA-Passwort des Empfängers immer die Rechnungsnummer des Vormonats ist, müssen die Passwörter regelmäßig aktualisiert werden. Dafür kann man ebenfalls eine CSV-Datei verwenden und folgende Eigenschaften eines GINA-Users aktualisieren:

  • userName
  • eMailAddress
  • mobile
  • question
  • answer
  • creator
  • customer
  • language
  • password
  • zip_attachment
  • expired

Wenn eine CSV-Datei mit diesen Werten und dem Wert eMailAddress zur Identifikation des Benutzers erzeugt wurde, kann man mit dem Befehl

Import-Csv .\examples\UpdateGINAUsers.csv |Set-SLGINAUser

die Daten der Gina-User ändern.

Optional SMS-Provider einbinden

Wenn GINA-User vorab angelegt werden, ist es gegebenenfalls sinnvoll, sie per SMS zu informieren, dass sie ab sofort GINA-Mails empfangen und lesen können. Viele SMS-Provider bieten dazu eine REST API-Schnittstelle an. Mit den Daten aus der CSV-Tabelle können die Mobiltelefonnummer und das Passwort verwendet werden, um auf einem „zweiten Weg“ den GINA-Empfänger über sein Kennwort zu informieren. Als Beispiel dient das nachfolgende Skript, welches den SMS-Dienst ASPSMS verwendet, um SMS zu versenden. Ein entsprechendes Credential-Objekt mit den Zugangsdaten zum SMS-Service muss vorher im Pfad c:\temp\aspsms.xml als verschlüsseltes XML existieren.

Dateiname: send-aspsms.ps1     

 

[CmdLetBinding()]

param(

    $mobile,

    $text

)

$cred = Import-CliXML c:\temp\aspsms.xml

$baseurl = ‚https://json.aspsms.com‘

$smsBodyHt = [ordered]@{

    UserName = $cred.UserName;

    Password = $cred.GetNetworkCredential().Password;

    Originator = „SEPPmail“;

    Recipients = @($mobile);

    MessageText = $text;

}

$smsJSONBody = ConvertTo-Json $smsBodyHt

$urlext = ‚/SendSimpleTextSMS‘

$uri = „$baseurl“+“$urlext“

Invoke-RestMethod -Credential $cred -Uri $uri -Method POST -body $smsJSONBody

Wenn Sie das Skript wie oben als ps1 abspeichern, lassen sich die Kundendaten verwenden und die Mobiltelefonnummer sowie beispielsweise das Passwort als SMS versenden.

 

$smsdata = Import-Csv .\examples\NewGINAUsers.csv|select-object mobile,password

foreach ($i in $smsdata) {

    & ./test/send-aspsms.ps1 -mobile $($i.mobile) -text „Ihr Zugangskennwort ist $($i.password)“

}

Damit können GINA-User vorab über ihr Kennwort informiert werden und sofort mit dem Lesen der verschlüsselten E-Mails loslegen.