API's gebruiken om CA's van derden voor SCEP toe te voegen aan Intune

  • Artikel

In Microsoft Intune kunt u externe certificeringsinstanties (CA' s) toevoegen en deze CA's certificaten laten uitgeven en valideren met behulp van het Simple Certificate Enrollment Protocol (SCEP). Een externe certificeringsinstantie toevoegen biedt een overzicht van deze functie en beschrijft de beheerderstaken in Intune.

Er zijn ook enkele ontwikkelaarstaken die gebruikmaken van een opensource-bibliotheek die Microsoft in GitHub.com heeft gepubliceerd. De bibliotheek bevat een API die:

  • Valideert het SCEP-wachtwoord dat dynamisch wordt gegenereerd door Intune
  • Geeft Intune een melding van de certificaten die zijn gemaakt op apparaten die SCEP-aanvragen indienen

Met behulp van deze API kan uw SCEP-server van derden worden geïntegreerd met de Intune SCEP-beheeroplossing voor MDM-apparaten. De bibliotheek abstrahert aspecten zoals verificatie, servicelocatie en de ODATA Intune-service-API van de gebruikers.

SCEP-beheeroplossing

Hoe SCEP van externe certificeringsinstantie kan worden geïntegreerd met Microsoft Intune

Met Intune kunnen beheerders SCEP-profielen maken en deze profielen vervolgens toewijzen aan MDM-apparaten. De SCEP-profielen bevatten parameters, zoals:

  • De URL van de SCEP-server
  • Het vertrouwde basiscertificaat van de certificeringsinstantie
  • Certificaatkenmerken en meer

Apparaten die bij Intune inchecken, krijgen het SCEP-profiel toegewezen en worden geconfigureerd met deze parameters. Een dynamisch gegenereerd SCEP-uitdagingswachtwoord wordt gemaakt door Intune en vervolgens toegewezen aan het apparaat.

Deze uitdaging bevat:

  • Het dynamisch gegenereerde uitdagingswachtwoord
  • De details van de parameters die worden verwacht in de aanvraag voor certificaatondertekening (CSR) die het apparaat aan de SCEP-server uitgeeft
  • De verlooptijd van de uitdaging

Intune versleutelt deze informatie, ondertekent de versleutelde blob en verpakt deze gegevens vervolgens in het wachtwoord voor de SCEP-uitdaging.

Apparaten die contact opnemen met de SCEP-server om een certificaat aan te vragen, geven vervolgens het wachtwoord voor de SCEP-uitdaging op. De SCEP-server verzendt het CSR- en versleutelde SCEP-uitdagingswachtwoord naar Intune voor validatie. Dit wachtwoord en deze CSR-aanvraag moeten worden gevalideerd voor de SCEP-server om een certificaat aan het apparaat uit te geven. Wanneer een SCEP-uitdaging wordt gevalideerd, worden de volgende controles uitgevoerd:

  • Valideert de handtekening van de versleutelde blob
  • Controleert of de uitdaging niet is verlopen
  • Valideert dat het profiel nog steeds is gericht op het apparaat
  • Controleert of de certificaateigenschappen die door het apparaat in de CSR zijn aangevraagd, overeenkomen met de verwachte waarden

De SCEP-beheeroplossing bevat ook rapportage. Een beheerder kan informatie krijgen over de implementatiestatus van het SCEP-profiel en over de certificaten die zijn uitgegeven aan de apparaten.

Integreren met Intune

De code voor de bibliotheek die moet worden geïntegreerd met de Intune SCEP kan worden gedownload in de GitHub-opslagplaats Microsoft/Intune-Resource-Access.

Het integreren van de bibliotheek in uw producten omvat de volgende stappen. Deze stappen vereisen kennis van het werken met GitHub-opslagplaatsen en het maken van oplossingen en projecten in Visual Studio.

  1. Registreren om meldingen van de opslagplaats te ontvangen

  2. De opslagplaats klonen of downloaden

  3. Ga naar de bibliotheek-implementatie die u nodig hebt onder de \src\CsrValidation map (https://github.com/Microsoft/Intune-Resource-Access/tree/develop/src/CsrValidation)

  4. Bouw de bibliotheek met behulp van de instructies in het README-bestand

  5. De bibliotheek opnemen in het project waarmee uw SCEP-server wordt gebouwd

  6. Voer de volgende taken uit op de SCEP-server:

    • Sta de beheerder toe om de Azure-toepassing-id, Azure-toepassing sleutel en tenant-id (in dit artikel) te configureren die door de bibliotheek worden gebruikt voor verificatie. Beheerders moeten de Azure-toepassing-sleutel kunnen bijwerken.
    • SCEP-aanvragen identificeren die een door Intune gegenereerd SCEP-wachtwoord bevatten
    • De api-bibliotheek Aanvraag valideren gebruiken om door Intune gegenereerde SCEP-wachtwoorden te valideren
    • Gebruik de bibliotheekmeldings-API's om Intune te informeren over certificaten die zijn uitgegeven voor SCEP-aanvragen met de door Intune gegenereerde SCEP-wachtwoorden. Stel Intune ook op de hoogte van fouten die kunnen optreden bij het verwerken van deze SCEP-aanvragen.
    • Controleer of de server voldoende informatie registreert om beheerders te helpen bij het oplossen van problemen

  7. Integratietests voltooien (in dit artikel) en eventuele problemen oplossen

  8. Geef de klant schriftelijke richtlijnen met uitleg over het volgende:

    • Hoe de SCEP-server moet worden ge onboardd in het Microsoft Intune-beheercentrum
    • De Azure-toepassing-id en Azure-toepassing sleutel ophalen die nodig zijn om de bibliotheek te configureren

SCEP-server onboarden in Azure

Voor verificatie bij Intune heeft de SCEP-server een Azure-toepassing-id, een Azure-toepassing-sleutel en een tenant-id nodig. De SCEP-server moet ook gemachtigd zijn voor toegang tot de Intune-API.

Om deze gegevens op te halen, meldt de beheerder van de SCEP-server zich aan bij de Azure Portal, registreert de toepassing, geeft de toepassing de validatiemachtiging Microsoft Intune API\SCEP-uitdaging en de machtiging Application.Read.All, maakt een sleutel voor de toepassing en downloadt vervolgens de toepassings-id, de sleutel en de tenant-id.

Zie Portal gebruiken voor het maken van een Microsoft Entra toepassing en service-principal voor toegang tot resources voor hulp bij het registreren van een toepassing en het ophalen van de id's en sleutels.

Java Library-API

De Java-bibliotheek wordt geïmplementeerd als een Maven-project dat de afhankelijkheden ophaalt wanneer deze wordt gebouwd. De API wordt geïmplementeerd onder de com.microsoft.intune.scepvalidation naamruimte door de IntuneScepServiceClient klasse.

IntuneScepServiceClient-klasse

De IntuneScepServiceClient klasse bevat de methoden die door de SCEP-service worden gebruikt om SCEP-wachtwoorden te valideren, Intune op de hoogte te stellen van certificaten die zijn gemaakt en om eventuele fouten weer te geven.

IntuneScepServiceClient-constructor

Handtekening:

IntuneScepServiceClient(
    Properties configProperties)

Beschrijving:

Hiermee wordt een IntuneScepServiceClient object geïnstitueert en geconfigureerd.

Parameters:

  • configProperties - Eigenschappenobject met clientconfiguratiegegevens

De configuratie moet de volgende eigenschappen bevatten:

  • AAD_APP_ID="De Azure-toepassing-id die is verkregen tijdens het onboardingproces"
  • AAD_APP_KEY="De Azure-toepassing sleutel die is verkregen tijdens het onboardingproces"
  • TENANT="De tenant-id die is verkregen tijdens het onboardingproces"
  • PROVIDER_NAME_AND_VERSION="Informatie die wordt gebruikt om uw product en de bijbehorende versie te identificeren"

Als uw oplossing een proxy vereist met verificatie of zonder verificatie, kunt u de volgende eigenschappen toevoegen:

  • PROXY_HOST="De host waarop de proxy wordt gehost."
  • PROXY_PORT="De poort waarop de proxy luistert."
  • PROXY_USER="De gebruikersnaam die moet worden gebruikt als de proxy basisverificatie gebruikt."
  • PROXY_PASS="Het wachtwoord dat moet worden gebruikt als de proxy gebruikmaakt van basisverificatie."

Gooit:

  • IllegalArgumentException : gegenereerd als de constructor wordt uitgevoerd zonder een juist eigenschapsobject.

Belangrijk

U kunt het beste een instantie van deze klasse instantiëren en deze gebruiken om meerdere SCEP-aanvragen te verwerken. Als u dit doet, vermindert u de overhead, omdat verificatietokens en servicelocatiegegevens in de cache worden opgeslagen.

Beveiligingsnotities
De SCEP-serveruitvoerfunctie moet de gegevens die zijn ingevoerd in de configuratie-eigenschappen die in de opslag zijn behouden, beveiligen tegen manipulatie en openbaarmaking. Het wordt aanbevolen om de juiste ACL's en versleuteling te gebruiken om de gegevens te beveiligen.

Methode ValidateRequest

Handtekening:

void ValidateRequest(
    String transactionId,
    String certificateRequest)

Beschrijving:

Valideert een SCEP-certificaataanvraag.

Parameters:

  • transactionId : de SCEP-transactie-id
  • certificateRequest - MET DER gecodeerde PKCS #10 Certificaataanvraag Base64 gecodeerd als een tekenreeks

Gooit:

  • IllegalArgumentException - Gegenereerd als deze wordt aangeroepen met een parameter die niet geldig is
  • IntuneScepServiceException - Gegenereerd als wordt vastgesteld dat de certificaataanvraag ongeldig is
  • Uitzondering : gegenereerd als er een niet-verwachte fout is opgetreden

Belangrijk

Uitzonderingen die door deze methode worden gegenereerd, moeten worden geregistreerd door de server. Houd er rekening mee dat de IntuneScepServiceException eigenschappen gedetailleerde informatie bevatten over waarom de validatie van de certificaataanvraag is mislukt.

Beveiligingsnotities:

  • Als deze methode een uitzondering genereert, mag de SCEP-server geen certificaat uitgeven aan de client.
  • Validatiefouten bij SCEP-certificaataanvragen kunnen duiden op een probleem in de Intune-infrastructuur. Of ze kunnen aangeven dat een aanvaller een certificaat probeert op te halen.
Methode SendSuccessNotification

Handtekening:

void SendSuccessNotification(
    String transactionId,
    String certificateRequest,
    String certThumbprint,
    String certSerialNumber,
    String certExpirationDate,
    String certIssuingAuthority)

Beschrijving:

Intune meldt dat er een certificaat is gemaakt als onderdeel van het verwerken van een SCEP-aanvraag.

Parameters:

  • transactionId : de SCEP-transactie-id
  • certificateRequest - MET DER gecodeerde PKCS #10 Certificaataanvraag Base64 gecodeerd als een tekenreeks
  • certThumprint - SHA1-hash van de vingerafdruk van het ingerichte certificaat
  • certSerialNumber - Serienummer van het ingerichte certificaat
  • certExpirationDate : vervaldatum van het ingerichte certificaat. De datumtijdtekenreeks moet worden opgemaakt als web UTC-tijd (JJJJ-MM-DDThh:mm:ss.sssTZD) ISO 8601.
  • certIssuingAuthority - Naam van de instantie die het certificaat heeft uitgegeven

Gooit:

  • IllegalArgumentException - Gegenereerd als deze wordt aangeroepen met een parameter die niet geldig is
  • IntuneScepServiceException - Gegenereerd als wordt vastgesteld dat de certificaataanvraag ongeldig is
  • Uitzondering : gegenereerd als er een niet-verwachte fout is opgetreden

Belangrijk

Uitzonderingen die door deze methode worden gegenereerd, moeten worden geregistreerd door de server. Houd er rekening mee dat de IntuneScepServiceException eigenschappen gedetailleerde informatie bevatten over waarom de validatie van de certificaataanvraag is mislukt.

Beveiligingsnotities:

  • Als deze methode een uitzondering genereert, mag de SCEP-server geen certificaat uitgeven aan de client.
  • Validatiefouten bij SCEP-certificaataanvragen kunnen duiden op een probleem in de Intune-infrastructuur. Of ze kunnen aangeven dat een aanvaller een certificaat probeert op te halen.
Methode SendFailureNotification

Handtekening:

void SendFailureNotification(
    String transactionId,
    String certificateRequest,
    long  hResult,
    String errorDescription)

Beschrijving:

Intune wordt gewaarschuwd dat er een fout is opgetreden tijdens het verwerken van een SCEP-aanvraag. Deze methode mag niet worden aangeroepen voor uitzonderingen die worden gegenereerd door de methoden van deze klasse.

Parameters:

  • transactionId : de SCEP-transactie-id
  • certificateRequest - MET DER gecodeerde PKCS #10 Certificaataanvraag Base64 gecodeerd als een tekenreeks
  • hResult - Win32-foutcode die de fout die is opgetreden het beste beschrijft. Zie Win32-foutcodes
  • errorDescription - Beschrijving van de fout die is opgetreden

Gooit:

  • IllegalArgumentException - Gegenereerd als deze wordt aangeroepen met een parameter die niet geldig is
  • IntuneScepServiceException - Gegenereerd als wordt vastgesteld dat de certificaataanvraag ongeldig is
  • Uitzondering : gegenereerd als er een niet-verwachte fout is opgetreden

Belangrijk

Uitzonderingen die door deze methode worden gegenereerd, moeten worden geregistreerd door de server. Houd er rekening mee dat de IntuneScepServiceException eigenschappen gedetailleerde informatie bevatten over waarom de validatie van de certificaataanvraag is mislukt.

Beveiligingsnotities:

  • Als deze methode een uitzondering genereert, mag de SCEP-server geen certificaat uitgeven aan de client.
  • Validatiefouten bij SCEP-certificaataanvragen kunnen duiden op een probleem in de Intune-infrastructuur. Of ze kunnen aangeven dat een aanvaller een certificaat probeert op te halen.
Methode SetSslSocketFactory

Handtekening:

void SetSslSocketFactory(
    SSLSocketFactory factory)

Beschrijving:

Gebruik deze methode om de client te informeren dat deze de opgegeven SSL-socketfactory moet gebruiken (in plaats van de standaardinstelling) bij de communicatie met Intune.

Parameters:

  • factory : de SSL-socketfactory die de client moet gebruiken voor HTTPS-aanvragen

Gooit:

  • IllegalArgumentException - Gegenereerd als deze wordt aangeroepen met een parameter die niet geldig is

Opmerking

De SSL Socket Factory moet indien nodig worden ingesteld voordat de andere methoden van deze klasse worden uitgevoerd.

Integratie testen

Valideren en testen of uw oplossing correct is geïntegreerd met Intune is een must. Hieronder ziet u een overzicht van de stappen:

  1. Een Intune-proefaccount instellen.
  2. Onboarding van de SCEP-server in de Azure Portal (in dit artikel).
  3. Configureer de SCEP-server met de id's en sleutel die zijn gemaakt tijdens het onboarden van uw SCEP-server.
  4. Registreer apparaten om de scenario's in de scenariotestmatrix te testen.
  5. Maak een vertrouwd basiscertificaatprofiel voor uw testcertificeringsinstantie.
  6. Maak SCEP-profielen om de scenario's te testen die worden vermeld in de scenariotestmatrix.
  7. Wijs de profielen toe aan gebruikers die hun apparaten hebben ingeschreven.
  8. Wacht tot de apparaten zijn gesynchroniseerd met Intune. Of synchroniseer de apparaten handmatig.
  9. Controleer of de profielen vertrouwd basiscertificaat en SCEP zijn geïmplementeerd op de apparaten.
  10. Controleer of het vertrouwde basiscertificaat op alle apparaten is geïnstalleerd.
  11. Controleer of de SCEP-certificaten voor de toegewezen profielen op alle apparaten zijn geïnstalleerd.
  12. Controleer of de eigenschappen van de geïnstalleerde certificaten overeenkomen met de eigenschappen die zijn ingesteld in het SCEP-profiel.
  13. Controleer of de uitgegeven certificaten correct worden weergegeven in het Intune-beheercentrum

Zie ook