> For the complete documentation index, see [llms.txt](https://docs.scepman.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scepman.com/de/zertifikatsverwaltung/api-certificates/scepmanclient.md). # SCEPmanClient SCEPmanClient ist ein PowerShell-Modul, das für die Interaktion mit SCEPmans REST-API vorgesehen ist. Da es plattformunabhängig und mit Windows PowerShell v5 kompatibel ist, können Sie dieses Modul verwenden, um Zertifikate für alle Anwendungsfälle anzufordern, für die die REST-API verwendet werden kann: * Automatische Ausstellung von Serverzertifikaten * Clientzertifikate für nicht verwaltete Geräte * Registrierung von Zertifikaten auf Linux-Geräten ## Installation Das Modul SCEPmanClient ist im PowerShell Gallery verfügbar und kann mit dem folgenden Befehl installiert werden: ```powershell Install-Module -Name SCEPmanClient ``` {% hint style="info" %} Folgen Sie der Anleitung von Microsoft zur Installation von PowerShell auf [Linux](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux?view=powershell-7.5) oder [MacOS](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-macos?view=powershell-7.5). {% endhint %} ## Voraussetzungen Damit das Modul wie erwartet funktioniert, müssen Sie an Ihrer SCEPman-Bereitstellung eine kleine Änderung vornehmen: {% stepper %} {% step %} ### Homepage-URL hinzufügen Fügen Sie die App Service-URL von SCEPman hinzu: Navigieren Sie zum `Branding & Properties` Bereich der App-Registrierung. Fügen Sie die App Service-URL von SCEPman dem Feld Homepage-URL hinzu:
Dies ist erforderlich, damit das Modul automatisch die Client-ID der App-Registrierung nachschlagen kann, die für das Abrufen des Zugriffstokens benötigt wird. {% endstep %} {% step %} ### Azure PowerShell die Interaktion mit der App-Registrierung erlauben Navigieren Sie in der App-Registrierung zu *Eine API verfügbar machen* und erstellen Sie einen benutzerdefinierten Scope, der verwendet werden kann, um die Client-ID zu autorisieren `1950a258-227b-4e31-a9cf-717495945fc2` (Microsoft Azure PowerShell)

Beispielinformationen für einen benutzerdefinierten API-Scope

Nach dem Erstellen eines API-Scope kann die Microsoft Azure PowerShell-Anwendung autorisiert werden:

Autorisierte Microsoft Azure PowerShell-Anwendung

{% endstep %} {% step %} ### EST-Endpunkt aktivieren #### Konfiguration *Erforderlich für die Zertifikatserneuerung* Konfigurieren Sie Ihren SCEPman App Service so, dass er mTLS-Clientzertifikate akzeptiert. Überprüfen Sie im Konfigurationsbereich des Abschnitts Einstellungen, dass der Clientzertifikatmodus unter Eingehende Clientzertifikate auf ***Optionaler interaktiver Benutzer***.
Setzen Sie den Clientzertifikatmodus nicht auf Erforderlich oder Zulassen, da dies den normalen Betrieb von SCEPman an den SCEP-Endpunkten beeinträchtigen würde! #### Umgebungsvariablen Um dieses Szenario nutzen zu können, müssen Sie die folgenden Umgebungsvariablen für den SCEPman App Service festlegen. #### [AppConfig:DbCSRValidation:Enabled](https://docs.scepman.com/advanced-configuration/application-settings/dbcsr-validation#appconfig-dbcsrvalidation-enabled) *Erforderlich für die Zertifikatsregistrierung und -erneuerung* Setzen Sie diese Variable auf ***true*** um die Validierung von Zertifikatsignierungsanforderungen (CSRs) zu aktivieren. #### [AppConfig:DbCSRValidation:AllowRenewals](https://docs.scepman.com/advanced-configuration/application-settings/dbcsr-validation#appconfig-dbcsrvalidation-allowrenewals) *Erforderlich für die Zertifikatserneuerung* Setzen Sie diese Variable auf ***true*** um Zertifikatserneuerungen zu aktivieren. #### [AppConfig:DbCSRValidation:ReenrollmentAllowedCertificateTypes](https://docs.scepman.com/advanced-configuration/application-settings/dbcsr-validation#appconfig-dbcsrvalidation-reenrollmentallowedcertificatetypes) *Erforderlich für die Zertifikatserneuerung* Setzen Sie diese Variable auf eine kommagetrennte Liste von Zertifikattypen, für die Sie die Erneuerung zulassen möchten. Eine Liste möglicher Zertifikattypen finden Sie in der verlinkten Variablendokumentation. Beispiel: ***Static,IntuneUser,IntuneDevice*** {% endstep %} {% endstepper %} ## Berechtigungen SCEPman verfügt über verschiedene Rollen, die das Registrieren unterschiedlicher Zertifikatstypen ermöglichen. Sie können diese in der *SCEPman-api* (Standardname) Enterprise-Anwendung zuweisen: #### CSR-DB-Anforderer Diese Rolle ist standardmäßig nur Service Principals (zum Beispiel App-Registrierungen) zuweisbar und ermöglicht das Anfordern von Zertifikaten mit beliebigen Betreffs und Verwendungszwecken. {% content-ref url="/pages/c6e9b6e18fdecafb14aaae14587abd1f7a62b135" %} [API-Registrierung](/de/zertifikatsverwaltung/api-certificates/api-enrollment.md) {% endcontent-ref %} #### CSR Self Service Diese Rolle kann Benutzern zugewiesen werden und ermöglicht die Registrierung von Zertifikaten mit den folgenden Einschränkungen: * Nur ClientAuth-EKU * Benutzerzertifikate müssen mit der UPN des Benutzers übereinstimmen, entweder im Betreff oder im alternativen UPN-Betreffnamen * Gerätezertifikate müssen einen Betreff oder SAN haben, den SCEPman einem Geräteobjekt zuordnen kann, das dem authentifizierten Benutzer gehört {% content-ref url="/pages/da7b8437e46f95216cec58f2994820fff20618fc" %} [Self-Service-Registrierung](/de/zertifikatsverwaltung/api-certificates/self-service-enrollment.md) {% endcontent-ref %} ## Anwendungsbeispiele ### Azure-Authentifizierung verwenden #### Interaktive Authentifizierung Wenn beim Anfordern eines neuen Zertifikats kein Authentifizierungsmechanismus angegeben wird, wird der Benutzer standardmäßig interaktiv authentifiziert. Mithilfe des `-SubjectFromUserContext` Parameters werden der Betreff und der UPN-SAN des Zertifikats automatisch basierend auf dem Kontext des angemeldeten Benutzers ausgefüllt: ```powershell New-SCEPmanCertificate -Url 'scepman.contoso.com' -SubjectFromUserContext -SaveToStore CurrentUser ``` #### Geräteanmeldung Wenn Sie auf einem System ohne Desktop-Umgebung ein neues Zertifikat anfordern möchten, können Sie den `-DeviceCode` Parameter verwenden, um die eigentliche Authentifizierung in einer anderen Sitzung durchzuführen: ```powershell New-SCEPmanCertificate -Url 'scepman.contoso.com' -DeviceCode -SubjectFromUserContext -SaveToFolder /home/user/certificates ``` #### Authentifizierung mit Service Principal In vollständig automatisierten Szenarien kann zur Authentifizierung eine App-Registrierung verwendet werden. Das Ableiten des Betreffs aus dem authentifizierten Kontext ist in diesem Fall nicht möglich. Parameter-Splatting macht die Ausführung außerdem lesbarer: ```powershell $Parameters = @{ 'Url' = 'scepman.contoso.com' 'ClientId' = '569fbf51-aa63-4b5c-8b26-ebbcfcde2715' 'TenantId' = '8aa3123d-e76c-42e2-ba3c-190cabbec531' 'ClientSecret' = 'csa8Q~aVaWCLZTzswIBGvhxUiEvhptuqEyJugb70' 'Subject' = 'CN=WebServer' 'DNSName' = 'Webserver.domain.local' 'ExtendedKeyUsage' = 'ServerAuth' 'SaveToStore' = 'LocalMachine' } New-SCEPmanCertificate @Parameters ``` ### Mit Zertifikaten authentifizieren Sobald ein Zertifikat unter Verwendung eines authentifizierten Kontexts ausgestellt wurde, können wir es erneuern, ohne erneut einen Kontext anzugeben. #### CertificateBySubject *Die Interaktion mit Keystores ist nur unter Windows möglich* Wenn Sie den `CertificateBySubject` Parameter angeben, versucht das Modul automatisch, im *CurrentUser* und *LocalMachine* Keystores ein geeignetes Zertifikat zur Erneuerung zu finden. Der eingegebene Wert wird per Regex mit den Betreffs aller verfügbaren Zertifikate verglichen. ```powershell New-SCEPmanCertificate -CertificateBySubject 'WebServer' -SaveToStore 'LocalMachine' ``` #### Ein bestimmtes Zertifikat angeben ```powershell $Certificate = Get-ChildItem Cert:\LocalMachine\My | Where-Object Thumbprint -eq '9B08EA68B16773CEF3C49D5D95BE50B784638984' New-SCEPmanCertificate -Certificate $Certificate -SaveToStore LocalMachine ``` #### CertificateFromFile Auf Linux-Systemen kann eine Zertifikatserneuerung durchgeführt werden, indem die Pfade eines vorhandenen Zertifikats und seines privaten Schlüssels übergeben werden. ```powershell New-SCEPmanCertificate -CertificateFromFile '~/certs/myCert.pem' -KeyFromFile '~/certs/myKey.key' -SaveToFolder '~/certs' ``` Bei Verwendung eines verschlüsselten privaten Schlüssels werden Sie nach dem Passwort gefragt. Sie können das Passwort des Schlüssels auch direkt mit dem `PlainTextPassword` Parameter übergeben. #### Verwendung von SCEPman mit einer Azure Web Application Firewall Bei aktivierten SSL-Profilen beendet die WAF die TLS-Verbindungen. Dadurch werden wiederum Zertifikatserneuerungen mit EST unterbrochen, da das Verfahren für die Authentifizierung auf mTLS angewiesen ist. In diesem Fall kann der `UseSCEPRenewal` Parameter verwendet werden, um stattdessen eine Zertifikatserneuerung nach dem SCEP-Protokoll durchzuführen. ```powershell New-SCEPmanCertificate -CertificateBySubject 'WebServer' -SaveToStore 'LocalMachine' -UseSCEPRenewal ``` Bitte beachten Sie, dass hierfür zusätzliche SCEPman-Konfigurationen bezüglich des statischen SCEP-Endpunkts erforderlich sind: * AppConfig:StaticValidation:Enabled : true * AppConfig:StaticValidation:AllowRenewals : true * AppConfig:StaticValidation:ReenrollmentAllowedCertificateTypes: Static (Abhängig von den für die Erneuerung vorgesehenen Typen) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.scepman.com/de/zertifikatsverwaltung/api-certificates/scepmanclient.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.