diff --git a/articles/connect-end-user-to-wifi-with-certificate.md b/articles/connect-end-user-to-wifi-with-certificate.md index 16a3e1c715..9057f9ee52 100644 --- a/articles/connect-end-user-to-wifi-with-certificate.md +++ b/articles/connect-end-user-to-wifi-with-certificate.md @@ -2,7 +2,7 @@ _Available in Fleet Premium_ -Fleet can help your end users connect to third-party tools like Wi-Fi or VPN by deploying certificates from your certificate authority (CA). Fleet currently supports [Okta](#okta), [DigiCert](#digicert), [Microsoft NDES](#microsoft-ndes),[Smallstep](#smallstep), [Hydrant](#hydrant), and a custom [SCEP](#custom-scep-simple-certificate-enrollment-protocol) or [EST](#custom-est-enrollment-over-secure-transport) server. +Fleet can help your end users connect to third-party tools like Wi-Fi or VPN by deploying certificates from your certificate authority (CA). Fleet currently supports [Okta](#okta), [DigiCert](#digicert), [Microsoft NDES](#microsoft-ndes), [Smallstep](#smallstep), [Hydrant](#hydrant), and a custom [SCEP](#custom-scep-simple-certificate-enrollment-protocol) or [EST](#custom-est-enrollment-over-secure-transport) server. Fleet will automatically renew certificates on Apple (macOS, iOS, iPadOS), Windows, and Android hosts before expiration. Learn more in the [Renewal section](#renewal). @@ -61,7 +61,7 @@ The following steps show how to deploy DigiCert certificates. ### Step 2: Create certificate profile in DigiCert -1. In DigiCert [Trust Lifcycle Manager](https://one.digicert.com/mpki/dashboard), select **Policies > Certificate profiles** from the main menu. Then select **Create profile from template** and select **Generic Device Certificate** from the list. +1. In DigiCert [Trust Lifecycle Manager](https://one.digicert.com/mpki/dashboard), select **Policies > Certificate profiles** from the main menu. Then select **Create profile from template** and select **Generic Device Certificate** from the list. 2. Add a friendly **Profile name** (e.g., "Fleet - Wi-Fi authentication"). 3. Select your **Business unit** and **Issuing CA**. 4. Select **REST API** from **Enrollment method**. Then select **3rd party app** from the **Authentication method** dropdown and select **Next**. @@ -71,7 +71,7 @@ The following steps show how to deploy DigiCert certificates. - For **Common name**, select **REST request** from **Source for the field's value** dropdown and check **Required**. - If you use **Other name (UPN)**, select **REST Request** and check both **Required** and **Multiple**. - Organizations usually use the device's serial number or the user's email. Fleet variables (covered in the next step) can be used to replace these variables with the actual values before the certificate is delivered to a device. -9. Click **Next** and leave the default options. +8. Click **Next** and leave the default options. ### Step 3: Connect Fleet to DigiCert @@ -80,7 +80,7 @@ The following steps show how to deploy DigiCert certificates. 3. Add a **Name** for your certificate authority. Best practice is all caps snake case (for example, "WIFI_AUTHENTICATION"). This name is used later as a variable name in a configuration profile. 4. If you're using DigiCert One's cloud offering, keep the default **URL**. If you're using a self-hosted (on-prem) DigiCert One, update the URL to match the one you use to log in to your DigiCert One. 5. In **API token**, paste your DigiCert server user's API token (from step 1). -6. In **Profile GUID**, paste your DigiCert One certificate profile GUID (from step 2). To your GUID, open the profile in DigiCert and copy **GUID** from the [Certificate profiles](https://one.digicert.com/mpki/policies/profiles) page. +6. In **Profile GUID**, paste your DigiCert One certificate profile GUID (from step 2). To find your GUID, open the profile in DigiCert and copy **GUID** from the [Certificate profiles](https://one.digicert.com/mpki/policies/profiles) page. 7. In **CN**, **UPN**, and **Certificate seat ID**, enter fixed values or select from [Fleet's host variables](https://fleetdm.com/docs/configuration/yaml-files#macos-settings-and-windows-settings). Most organizations use the host's serial number or end user's email to deliver a certificate that's unique to the host. 8. Select **Add CA**. Your DigiCert certificate authority (CA) should appear in your list of CAs in Fleet. @@ -98,7 +98,7 @@ When Fleet delivers the profile to your hosts, Fleet will replace the variables. ### Additional DigiCert details: - Each DigiCert device type seat (license) can have multiple certificates only if they have the same CN and seat ID. If a new certificate has a different CN, a new DigiCert license is required. -- If the value for any variable used in step 3 above changes, Fleet will resend the profile. This means that if you use a variable like `$FLEET_VAR_HOST_END_USER_IDP_USERNAME` for CN or seat ID, and the variable's value changes, Fleet will get a new certificate and create a new seat in DigiCert. This will add a new DigiCert license. If you want to revoke a license in DigiCert, head to [**Trust Lifcycle Manager > Account > Seats**](https://one.digicert.com/mpki/account/seats) and remove the seat. +- If the value for any variable used in step 3 above changes, Fleet will resend the profile. This means that if you use a variable like `$FLEET_VAR_HOST_END_USER_IDP_USERNAME` for CN or seat ID, and the variable's value changes, Fleet will get a new certificate and create a new seat in DigiCert. This will add a new DigiCert license. If you want to revoke a license in DigiCert, head to [**Trust Lifecycle Manager > Account > Seats**](https://one.digicert.com/mpki/account/seats) and remove the seat. - DigiCert seats aren't automatically revoked when hosts are deleted in Fleet. To revoke a license, ask the team that owns DigiCert to follow the instructions above. #### Example configuration profile @@ -150,7 +150,7 @@ The following steps show how to deploy [Microsoft NDES](https://learn.microsoft. ### Step 1: Connect Fleet to NDES -1. In Fleet, head to **Settings > **Integrations > Certificates**. +1. In Fleet, head to **Settings > Integrations > Certificates**. 2. Select the **Add CA** button and select **Okta CA or Microsoft NDES** in the dropdown. 3. Enter your **SCEP URL**, **Admin URL**, and **Username** and **Password**. 4. Select **Add CA**. Your NDES certificate authority (CA) should appear in the list in Fleet. @@ -161,7 +161,7 @@ When saving the configuration, Fleet will attempt to connect to the SCEP server ### Step 2: Add SCEP configuration profile to Fleet -1. Create a [configuration profile](https://fleetdm.com/guides/custom-os-settings) with the SCEP payload. In the profile, for `Challenge`, use`$FLEET_VAR_NDES_SCEP_CHALLENGE`. For `URL`, use `$FLEET_VAR_NDES_SCEP_PROXY_URL`, and make sure to add `$FLEET_VAR_SCEP_RENEWAL_ID` to `OU`. +1. Create a [configuration profile](https://fleetdm.com/guides/custom-os-settings) with the SCEP payload. In the profile, for `Challenge`, use `$FLEET_VAR_NDES_SCEP_CHALLENGE`. For `URL`, use `$FLEET_VAR_NDES_SCEP_PROXY_URL`, and make sure to add `$FLEET_VAR_SCEP_RENEWAL_ID` to `OU`. 2. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can also use any of the [Apple's built-in variables](https://support.apple.com/en-my/guide/deployment/dep04666af94/1/web/1.0). @@ -266,10 +266,10 @@ Currently, using the Smallstep-Jamf connector is the best practice. Fleet is tes ### Step 3: Add SCEP configuration profile to Fleet 1. Create a [configuration profile](https://fleetdm.com/guides/custom-os-settings) with the SCEP payload. - - For `Challenge`, use`$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_{CA_NAME}`. + - For `Challenge`, use `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_{CA_NAME}`. - For `URL`, use `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_{CA_NAME}`, and make sure to add `$FLEET_VAR_SCEP_RENEWAL_ID` to `OU`. -2. Replace the `{CA_NAME}` with the name you created in step 2. For example, if the name of the CA is "WIFI_AUTHENTICATION", the variables will look like this: `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_WIFI_AUTHENTICATION` and `FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_WIFI_AUTHENTICATION`. +2. Replace the `{CA_NAME}` with the name you created in step 2. For example, if the name of the CA is "WIFI_AUTHENTICATION", the variables will look like this: `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_WIFI_AUTHENTICATION` and `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_WIFI_AUTHENTICATION`. 3. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can also use any of the [Apple's built-in variables](https://support.apple.com/en-my/guide/deployment/dep04666af94/1/web/1.0). @@ -362,7 +362,7 @@ The flow for Hydrant differs from the other certificate authorities (CA's). Whil 2. Select **Add CA** and then choose **Hydrant EST** in the dropdown. 3. Add a **Name** for your certificate authority. The best practice is to create a name based on your use case in all caps snake case (ex. "WIFI_AUTHENTICATION"). 4. Add your Hydrant EST **URL**. -5. Add the Hydrant ID and Key as the **Client ID** and **Client secret** in Fleet respectfully. +5. Add the Hydrant ID and Key as the **Client ID** and **Client secret** in Fleet respectively. 6. Click **Add CA**. Your Hydrant certificate authority (CA) should appear in the list in Fleet. ### Step 3: Create a custom script @@ -407,7 +407,7 @@ curl 'https:///api/latest/fleet/certificate_authorities/ /opt/company/certificate.pem ``` -This script assumes that your company installs a custom Company Portal app or something similar at `/opt/company`, gathers the user's IdP session information, uses username and a password to protect the private key from `/opt/company/userinfo`, and installs that the certificate in `/opt/company`. You will want to modify it to match your company's requirements. +This script assumes that your company installs a custom Company Portal app or something similar at `/opt/company`, gathers the user's IdP session information, uses username and a password to protect the private key from `/opt/company/userinfo`, and installs the certificate in `/opt/company`. You will want to modify it to match your company's requirements. For simplicity, the scripts use a `userinfo` file (below). However, the best practice is to load variables from the output of a command or even a separate network request: @@ -439,7 +439,7 @@ The following steps show how to deploy certificates from any certificate authori ### Step 1: Connect Fleet to a custom SCEP server -1. In Fleet, head to **Settings > **Integrations > Certificates**. +1. In Fleet, head to **Settings > Integrations > Certificates**. 2. Select the **Add CA** button and select **Custom** in the dropdown. 3. Add a **Name** for your certificate authority. The best practice is to create a name based on your use case in all caps snake case (for example, "WIFI_AUTHENTICATION"). This name will be used later as a variable name in a configuration profile. 4. Add your **SCEP URL** and **Challenge**. @@ -451,9 +451,9 @@ To deploy SCEP certificates to macOS, iOS, iPadOS, and Windows hosts, we'll foll For Android hosts, we use a configuration profile and a certificate template. Follow the [Android steps](#android-deploy-certificate) instead. -1. Create a [configuration profile](https://fleetdm.com/guides/custom-os-settings) with the SCEP payload. In the profile, for `Challenge`, use`$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_{CA_NAME}`. For `URL`, use `$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_{CA_NAME}`, and make sure to add `$FLEET_VAR_SCEP_RENEWAL_ID` to `OU`. +1. Create a [configuration profile](https://fleetdm.com/guides/custom-os-settings) with the SCEP payload. In the profile, for `Challenge`, use `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_{CA_NAME}`. For `URL`, use `$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_{CA_NAME}`, and make sure to add `$FLEET_VAR_SCEP_RENEWAL_ID` to `OU`. -2. Replace the `{CA_NAME}` with the name you created in step 3. For example, if the name of the CA is "WIFI_AUTHENTICATION", the variables will look like this: `$FLEET_VAR_CUSTOM_SCEP_PASSWORD_WIFI_AUTHENTICATION` and `FLEET_VAR_CUSTOM_SCEP_DIGICERT_DATA_WIFI_AUTHENTICATION`. +2. Replace the `{CA_NAME}` with the name you created in step 3. For example, if the name of the CA is "WIFI_AUTHENTICATION", the variables will look like this: `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_WIFI_AUTHENTICATION` and `$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_WIFI_AUTHENTICATION`. 3. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can also use any of [Apple's built-in variables](https://support.apple.com/en-my/guide/deployment/dep04666af94/1/web/1.0). @@ -465,7 +465,7 @@ When the profile is delivered to your hosts, Fleet will replace the variables. I How to deploy SCEP certificates to Android hosts: -1. Create a `add-certificates-to-work-profile.json` file, copy/paste the below JSON into it, and then, in Fleet, head to to **Controls > OS settings > Custom settings**, select **Add profile**, and upload your new `add-certificates-to-work-profile.json` profile. +1. Create a `add-certificates-to-work-profile.json` file, copy/paste the below JSON into it, and then, in Fleet, head to **Controls > OS settings > Custom settings**, select **Add profile**, and upload your new `add-certificates-to-work-profile.json` profile. ```json { @@ -678,7 +678,7 @@ The flow for EST is similar to Hydrant, and differs from the other certificate a ### Step 1: Obtain API credentials -This step will vary depending between providers. EST servers require a `username` and `password` for authentication. These may be obtained from your company's certificate authority administrator. +This step will vary between providers. EST servers require a `username` and `password` for authentication. These may be obtained from your company's certificate authority administrator. ### Step 2: Connect Fleet to the custom EST server @@ -686,7 +686,7 @@ This step will vary depending between providers. EST servers require a `username 2. Select **Add CA** and then choose **Custom EST Proxy** in the dropdown. 3. Add a **Name** for your certificate authority. The best practice is to create a name based on your use case in all caps snake case (ex. "WIFI_AUTHENTICATION"). 4. Add your Custom EST Proxy **URL**. -5. Add the username and password as the **Username** and **Password** in Fleet respectfully. +5. Add the username and password as the **Username** and **Password** in Fleet respectively. 6. Click **Add CA**. Your Custom EST Proxy certificate authority (CA) should appear in the list in Fleet. ### Step 3: Create a custom script @@ -731,7 +731,7 @@ curl 'https:///api/latest/fleet/certificate_authorities/ /opt/company/certificate.pem ``` -This script assumes that your company installs a custom Company Portal app or something similar at `/opt/company`, gathers the user's IdP session information, uses username and a password to protect the private key from `/opt/company/userinfo`, and installs that the certificate in `/opt/company`. You will want to modify it to match your company's requirements. +This script assumes that your company installs a custom Company Portal app or something similar at `/opt/company`, gathers the user's IdP session information, uses username and a password to protect the private key from `/opt/company/userinfo`, and installs the certificate in `/opt/company`. You will want to modify it to match your company's requirements. For simplicity, the scripts use a `userinfo` file (below). However, the best practice is to load variables from the output of a command or even a separate network request: @@ -784,13 +784,13 @@ You can deploy a user-scoped certificate on macOS and Windows hosts using a user For macOS hosts, user-scoped certificates only work if the `login` keychain is unlocked. If it's locked, MDM commands to install the certificate configuration profile will always return `NotNow`. To check whether the `login` keychain is unlocked, open Keychain Access on the Mac. An unlocked icon should appear to the left of the `login` keychain under **Default keychains**. If it's locked, right-click on the `login` keychain to unlock it. -### Editing ceritificate configuration profiles on Apple (macOS, iOS, iPadOS) hosts +### Editing certificate configuration profiles on Apple (macOS, iOS, iPadOS) hosts When you edit a certificate configuration profile for Apple hosts, via GitOps, a new certificate will be added to each hosts' Keychain and the old certificate will be removed. It takes a couple minutes for the old certificate to be removed. ### HTTP signatures -If you're deploying certificates from a [custom EST](#custom-est-enrollment-over-secure-transport) certificate authority, you can use HTTP signatures instead of a Fleet API token to authenticate request to Fleet's ["Request certificate" endpoint](https://fleetdm.com/docs/rest-api/rest-api#request-certificate). +If you're deploying certificates from a [custom EST](#custom-est-enrollment-over-secure-transport) certificate authority, you can use HTTP signatures instead of a Fleet API token to authenticate requests to Fleet's ["Request certificate" endpoint](https://fleetdm.com/docs/rest-api/rest-api#request-certificate). This is only supported on Linux hosts with TPM (Trusted Platform Module) hardware that enroll to Fleet using a Fleet agent generated (`fleetctl package`) with the `--fleet-managed-host-identity-certificate` flag. @@ -855,7 +855,7 @@ An example CAThumprint looks like this: `2133EC6A3CFB8418837BB395188D1A62CA2B96A 1. In your browser, open the following URL to download a certificate: https:///scep?operation=GetCACert 2. Run the following command to get the SHA1 Thumbprint: - 1. **Terminal (macOS)** -> `openssl x509 -inform DER -in /path/to/downloaded-cert.cer -noout -fingerprint -sha1 | sed 's/sha1 Fingerprint=//; s/://g` + 1. **Terminal (macOS)** -> `openssl x509 -inform DER -in /path/to/downloaded-cert.cer -noout -fingerprint -sha1 | sed 's/sha1 Fingerprint=//; s/://g'` 2. **PowerShell (Windows)** -> `$cert = Get-PfxCertificate -FilePath "Z:\scep (1).cer";$cert.Thumbprint` 3. It will return the SHA1 Thumbprint without colons and text. Copy this. 4. Use the copied value for `./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/CAThumbprint` option.