// to display images directly on GitHub
ifdef::env-github[]
:encoding: UTF-8
:lang: en
:doctype: book
:toc: left
:imagesdir: ../../images
endif::[]

////

    This file is part of the PacketFence project.

    See PacketFence_Installation_Guide.asciidoc
    for authors, copyright and license information.

////


//=== PacketFence PKI

This section has been created to give a quick start to configure the PacketFence PKI in PacketFence. This guide does not include advanced troubleshooting of EAP-TLS connections. Refer to the relevant documentation of EAP-TLS, RADIUS and OpenSSL for advanced features. The PKI comes installed by default since PacketFence version 10. All certificates would be saved in the database. If you want to migrate your certificate from the old PacketFence PKI please see the upgrade section.

==== Certificate Authority creation

You will need to create a new certificate authority. Go to the PacketFence web administration under the section Configuration -> Integration -> PKI -> Certificate Authorities and click on *New Certificate Authority*

image::packetfence-pki-ca_menu.png[scaledwidth="100%",alt="Certification authority creation"]

Optionally if you want the CA to be a sub-CA of another PKI then you can click on 'Generate CSR' (top right of the CA form), modify the information (if needed) and click 'Generate CSR'. On the next page copy the CSR and provide it to the external CA to be able to retrieve a Signed Certficate. On the last page provide the Signed Certificate and click 'Save'.

If the CA certificate is about to expire, generate a new CSR or click on Resign CA Certificate (self-signed).

===== Here's a CA example:

image::packetfence-pki-ca_creation.png[scaledwidth="100%",alt="Certification authority creation"]


===== Once you have created the CA, you should see the Root CA certificate displayed at the bottom of the page:

image::packetfence-pki-ca_created.png[scaledwidth="100%",alt="Certification authority config"]

Once done copy the certificate in the clipboard from the Certificate Authorities list (Configuration -> Integration -> PKI -> Certificate Authorities and click on *Copy Certificate*) then edit the RADIUS certificate section in Configuration -> Systen Configuration -> SSL Certificates -> RADIUS -> Edit and paste the public key in "Certificate Authority" and Save. (Don't forget to restart radiusd-auth)

This will authorize the EAP TLS authentications using the PKI issued certificates.

==== Template creation

Now you will need to create a certificate template that will gather all the settings for your certificate like the validity period or the certificate usage.

===== Select the Certificate Authority previously created:

image::packetfence-pki-template_menu.png[scaledwidth="100%",alt="Template configuration"]

===== Here's a template example:

image::packetfence-pki-template_creation.png[scaledwidth="100%",alt="Template configuration"]

Key usage clientAuth: To use your certificate for a client authentication.

Key usage serverAuth: If you want to install your certificate on a server.

===== P12 mail password emailed to the users:

image::packetfence-pki-template_password_email.png[scaledwidth="100%",alt="Template configuration"]

===== SCEP

You can choose to enable SCEP on this template.

image::packetfence-pki-scep.png[scaledwidth="100%",alt="SCEP configuration"]


IMPORTANT: Common name and Subject Alt Name attributes provided in CSR to get a certificate through SCEP will override values in PKI template.
Other values like Signature Algorithm, Key usage, Extended key usage will be taken from PKI template.

Optionally, enable 'SCEP Server Enabled' and define an external SCEP server to proxy the request.

====== SCEP Test

Let's do a scep request by hand.
Directly from the PacketFence server do that:

Create a private key and a csr file:

 openssl req -newkey rsa:2048 -keyout PRIVATEKEY.key -out MYCSR.csr

 Generating a 2048 bit RSA private key
 .........................................................................................................................................................................+++
 .........................+++
 writing new private key to 'PRIVATEKEY.key'
 Enter PEM pass phrase:
 Verifying - Enter PEM pass phrase:
 -----
 You are about to be asked to enter information that will be incorporated
 into your certificate request.
 What you are about to enter is what is called a Distinguished Name or a DN.
 There are quite a few fields but you can leave some blank
 For some fields there will be a default value,
 If you enter '.', the field will be left blank.
 -----
 Country Name (2 letter code) [XX]:CA
 State or Province Name (full name) []:QC
 Locality Name (eg, city) [Default City]:Montreal
 Organization Name (eg, company) [Default Company Ltd]:Acme
 Organizational Unit Name (eg, section) []:IT
 Common Name (eg, your name or your server's hostname) []:acme.com
 Email Address []:admin@acme.com

 Please enter the following 'extra' attributes
 to be sent with your certificate request
 A challenge password []:password
 An optional company name []:

Get the CA certificate:

 sscep getca  -u http://ip_address/scep/template_name -c ./ca-prefix -i MyPKI -v -d

 sscep: starting sscep, version 0.6.1
 sscep: new transaction
 sscep: transaction id: SSCEP transactionId
 sscep: hostname: ip_address
 sscep: directory: scep/template_name
 sscep: port: 80
 sscep: SCEP_OPERATION_GETCA
 sscep: requesting CA certificate
 sscep: scep msg: GET /scep/template_name?operation=GetCACert&message=MyPKI HTTP/1.0

 sscep: server returned status code 200
 sscep: MIME header: application/x-x509-ca-cert
 sscep: valid response from server
 sscep: MD5 fingerprint: 22:DE:09:17:8B:5F:94:1E:EB:0D:9C:12:EF:05:F0:C5
 sscep: CA certificate written as ./ca-prefix

Remove the private key passphrase:

 openssl rsa -in PRIVATEKEY.key -out private.key
 Enter pass phrase for PRIVATEKEY.key:
 writing RSA key

Send the CSR and retreive the certificate:

 sscep enroll -c ./ca-prefix  -k ./private.key -r ./MYCSR.csr -u http://ip_address/scep/template_name -S sha1 -l ./cert.crt

==== Certificate creation

image::packetfence-pki-certificate_menu.png[scaledwidth="100%",alt="Certificate creation"]

image::packetfence-pki-certificate_creation.png[scaledwidth="100%",alt="Certificate creation"]

===== Once it's created, you can send it to the email user or download the p12 format:

image::packetfence-pki-certificate_download.png[scaledwidth="100%",alt="Certificate creation"]

==== PEM format

The PacketFence PKI hand out PKCS12 certificates, if you want to convert your certificate to PEM format, you can use the commands:

----
openssl pkcs12 -in YourCert.p12 -nocerts -out YourCert.key -nodes
openssl pkcs12 -in YourCert.p12 -out YourCert.pem -clcerts -nokeys
----

==== Revoke a certificate

If you revoke a certificate it can't be recovered and you would need to recreate a new one. You will need to specify a reason of the revokation.

===== Click on the *Revoke* button on the certificate:

image::packetfence-pki-revoked_certificate.png[scaledwidth="100%",alt="Revoke a certificate"]

==== Resign a certificate

Resign-ing an existing Certificate will extend the duration by reusing the private-key to generate a new public certificate.
Click the 'Resign' button (top-right), modify the information (if needed) and click 'Resign'.


==== PKI Provider

You can hand out certificate to non-BYOD device on a captive portal.

First, you would need to create the PKI provider that will query the PacketFence PKI for new certifcate. Go to Configuration -> Advanced Access Configuration -> PKI provider

image::packetfence-pki-pki-provider_menu.png[scaledwidth="100%",alt="PKI Provider"]

===== Create a certificate per user or per device mac address, this example will cover one certificate per device:

image::packetfence-pki-pki-provider_creation.png[scaledwidth="100%",alt="PKI Provider"]


==== Intune Integration

===== Azure configuration

You can hand out certificates when you use intune enrolment.

First you need to create an application on Azure that allow PacketFence to connect to the Intune API.

To do that first you have to go in Azure portal and App registration then click *New registration*

image::Intune-1-App-Registration.png[scaledwidth="100%",alt="App-Registration"]

Next set a Name and in "Supported account types" select "Accounts in this organizational directory only" then click *Register*

image::Intune-2-Register-Application.png[scaledwidth="100%",alt="Register-Application"]

On the next page you have to copy the "Application (Client) ID" and the "Directory (tenant) ID", thoses will be needed to configure PacketFence.

image::Intune-3-App-Detail.png[scaledwidth="100%",alt="Application-Detail"]

Then you need to generate a "Client secrets", to do that click on "Add a certificate or secret"

image::Intune-4-App-Certificates-Secrets.png[scaledwidth="100%",alt="App-Certificates-Secrets"]

image::Intune-5-Add-Client-Secret.png[scaledwidth="100%",alt="Add-Client-Secret"]

Copy the "Value" of the secret, this is the only time you should be able to see it.

image::Intune-6-Copy-Client-Secret.png[scaledwidth="100%",alt="Copy-Client-Secret"]

Next you have to add API permissions, click on "API permissions" -> "Add a Permissions":

 Intune -> "Application permissions" and select "scep_challenge_provider"
 Microsoft Graph -> "Application permissions" and select "Application.Read.All"
 Microsoft Graph -> "Delegated permissions" and select "User.Read"

For more details about permissions https://techcommunity.microsoft.com/t5/intune-customer-success/support-tip-intune-service-discovery-api-endpoint-will-require/ba-p/2428040

Previous versions used Azure Active Directory Graph which is now deprecated and will stop working after December 2022, if you have granted those permissions you must remove them and add the new permissions instead.

image::Intune-7-API-Permissions.png[scaledwidth="100%",alt="API-Permissions"]

Last step is to "Grant admin", just click on "Grant admin consent for ..." and click *Yes*

image::Intune-8-Grant-Admin.png[scaledwidth="100%",alt="Grant-Admin"]

CAUTION: Key storage provider (KSP) needs to be set to *Enroll to Software KSP*

image::Intune_KSP.png[scaledwidth="100%",alt="KSP"]

===== PacketFence configuration

====== Intune definition

First of all you have to define the configuration parameters to reach the Intune API.
To do that go in Configuration -> Integration -> Cloud Services -> New Cloud -> Microsoft Intune

Next fill the field with the values taken from the Azure portal ("Application (Client) ID" , "Directory (tenant) ID" and "Client secrets") and *Create*.

image::Intune-9-PacketFence-Intune.png[scaledwidth="100%",alt="PacketFence-Intune"]

====== SCEP configuration

Now let's configure the PKI template to enable SCEP on it. (go to the previous section on how to configure a template in the PKI)

Go in Configuration -> Integration -> PKI -> Templates and edit the one you created previously.

You can see that there is a SCEP section. Enable SCEP and check Enable Cloud Integration and select the Cloud Service you created previously. (In the case the SCEP challenge password is not mandatory).

image::Intune-10-PacketFence-SCEP.png[scaledwidth="100%",alt="PacketFence-SCEP"]

Starting from now the scep server will be available on each ip where the portal is running (you need to enable the portal on the management interface if you want to be able to do SCEP on this interface).

The URL of the SCEP server will be available on http://ip_addresse/scep/template_name (https too) where template_name is the name of your template in the PKI.



===== Intune configuration

For this section you can follow the instruction on the Microsoft web site:

 https://docs.microsoft.com/en-us/mem/intune/protect/certificates-profile-scep

From the PacketFence server you will need to extract the PKI Ca certificate associated to the template and put it in Intune as a "trusted certificate"

Then set the SCEP URL to http://ip_addresse/scep/template_name or https://ip_addresse/scep/template_name

