diff --git a/manifest.json b/manifest.json index 23cde88c..2f750013 100644 --- a/manifest.json +++ b/manifest.json @@ -45,13 +45,17 @@ "path": "/platform/smallstep-agent.mdx" }, { - "title": "Connect Jamf Pro", - "path": "/tutorials/connect-jamf-pro-to-smallstep.mdx" + "title": "Connect Google Workspace", + "path": "/tutorials/connect-google-workspace-to-smallstep.mdx" }, - { + { "title": "Connect Intune", "path": "/tutorials/connect-intune-to-smallstep.mdx" }, + { + "title": "Connect Jamf Pro", + "path": "/tutorials/connect-jamf-pro-to-smallstep.mdx" + }, { "title": "Connect Workspace One UEM", "path": "/tutorials/connect-workspace-one-to-smallstep.mdx" @@ -78,13 +82,17 @@ "title": "Set up Wi-Fi Access Points for EAP-TLS", "path": "/tutorials/wifi-setup-guide.mdx" }, + { + "title": "Deploy EAP-TLS Wi-Fi with Intune", + "path": "/tutorials/intune-mdm-setup-guide.mdx" + }, { "title": "Deploy EAP-TLS Wi-Fi with Jamf Pro", "path": "/tutorials/apple-mdm-jamf-setup-guide.mdx" }, { - "title": "Deploy EAP-TLS Wi-Fi with Intune", - "path": "/tutorials/intune-mdm-setup-guide.mdx" + "title": "Deploy EAP-TLS Wi-Fi with Google Workspace", + "path": "/tutorials/google-workspace-mdm-setup-guide.mdx" }, { "title": "Wi-Fi Authentication Webhooks", diff --git a/step-ca/acme-basics.mdx b/step-ca/acme-basics.mdx index 87b7bb9f..7301756c 100644 --- a/step-ca/acme-basics.mdx +++ b/step-ca/acme-basics.mdx @@ -42,10 +42,21 @@ This tutorial assumes you have initialized and started up a `step-ca` server (se With ACME, machines can get certificates from a CA without any human interaction involved. It is used by public Web PKI CAs (eg. Let's Encrypt) and by private, internal CAs. -ACME allows the CA to prove that a client controls a set of resources for the purpose of certificate issuance. -ACME doesn't restrict _who_ can make requests of the CA. -There is an extension to ACME called External Account Binding (EAB) which adds keys for ACME accounts, -and this feature is available in Smallstep's commercial CA software. +ACME allows the CA to prove that a client controls an identifier +(a domain name, for example) +for the purpose of certificate issuance. +It _authenticates_ certificate requests, +but it does not _authorize_ them. +ACME can't determine whether a client +is the rightful owner of the identifier, +or merely an entity currently controlling it. + +It's up to you to add authorization or policy enforcement layers to your infrastructure, +and to protect your network, hosts, and DNS appropriately. + +There is an extension to ACME called External Account Binding (EAB) which adds an authorization layer, +using pre-registered client credentials. +This feature is available in Smallstep's commercial CA software. ## A Typical ACME Flow diff --git a/tutorials/connect-google-workspace-to-smallstep.mdx b/tutorials/connect-google-workspace-to-smallstep.mdx new file mode 100644 index 00000000..8f7e3083 --- /dev/null +++ b/tutorials/connect-google-workspace-to-smallstep.mdx @@ -0,0 +1,90 @@ +--- +updated_at: October 02, 2025 +title: Connect Google Workspace to Smallstep +html_title: Integrate Google Workspace with Smallstep Tutorial +description: Integrate Google Workspace with Smallstep for Chromebook device security. Complete guide for enforcing device trust in ChromeOS environments. +--- + +Smallstep can integrate with Google Workspace to keep your ChromeOS device inventory in sync. + +# Prerequisites + +You will need: + +- A [Smallstep team](https://smallstep.com/signup) +- A Google Workspace tenant, with ability to manage domain-wide delegation +- A Google Cloud project, with ability to create service accounts and keys + +# Step-by-step instructions + +In Google Cloud Console, select a project you will use for Smallstep. This can be any project, as long as you can grant domain-wide delegation to the client in a future step. + +Your Google Cloud project must have the Admin SDK API enabled. By default, it is disabled. + +### 0. Enable Admin SDK API + +1. Go to [Admin SDK API](https://console.cloud.google.com/apis/api/admin.googleapis.com) for your project, and choose **Enable API** + +### 1. Create a Service Account for Smallstep + +1. In Google Cloud, visit [IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) +2. Choose **Create service account** +3. Give the **Service account name**, e.g. `Smallstep Google Workplace Sync` +4. Optionally, provide a **Description** for the account +5. Choose **Done** +6. Open the details for the Service Account you just created +7. Copy the **Unique ID** (numeric) and the **Email** shown on the details tab; you’ll need them later +8. Visit the **Keys** tab, and choose **Add key**, then **Create new key** +9. Choose **Create** to create a JSON key + +A file containing the service account key will be downloaded. Keep this safe and secure! + +### 2. Grant device directory API permissions + +1. In Google Admin, visit [Security → Access and data control → API controls](https://admin.google.com/ac/owl) +2. Under Domain wide delegation, select **Manage Domain Wide Delegation** +3. In the **API Clients** table, select **Add new** + 1. Enter the **Unique ID** of the service account from Step 1 + 2. For the **OAuth Scopes**, enter the following scope: + + ``` + https://www.googleapis.com/auth/admin.directory.device.chromeos + ``` + + 3. Choose **Authorize** + +### 3. Add Google Workspace to Smallstep + +In Smallstep, visit [Settings → Device Management](https://smallstep.com/app/?next=/settings/devices). + +Configure a new Google Workspace Integration with the following values: + +- The **Customer ID** of your Google Workspace tenant. The Customer ID is a short alphanumeric string. It can be obtained from the Google Workspace Admin [Account Settings](https://admin.google.com/ac/accountsettings/profile) page +- The **Service Account JSON key** you downloaded earlier +- An email address of a user in your Google Workspace directory with admin permissions + +### 4. Add Smallstep Certificates to Google Workspace + +After saving the Google Workspace connection, you will see settings for your integration. + +1. Download the following Authority Certificates: + - Smallstep Devices Root CA + - Smallstep Devices Intermediate CA + - Smallstep Agents Root CA + - Smallstep Agents Intermediate CA + +2. In Google Workspace, visit [Devices → Networks → Certificates](https://admin.google.com/ac/networks/certificates). +3. Choose an Organizational Unit, if desired +4. Choose **Add certificate** + + In the modal, configure the following: + + - Provide a descriptive name, e.g. `Smallstep Devices Root` + - Upload the PEM file for the Smallstep Devices Root CA + - Check ✅ **Enabled for Chromebook** + - Choose **Add** +5. Repeat Step 4 for each of the certificates you downloaded + +### Confirmation + +Within a few minutes, you should see all of your ChromeOS devices in Smallstep's [Devices](https://smallstep.com/app/?next=/devices/all) tab. Your device inventory will sync every four hours. diff --git a/tutorials/google-workspace-mdm-setup-guide.mdx b/tutorials/google-workspace-mdm-setup-guide.mdx new file mode 100644 index 00000000..3ef5f493 --- /dev/null +++ b/tutorials/google-workspace-mdm-setup-guide.mdx @@ -0,0 +1,68 @@ +--- +updated_at: October 02, 2025 +title: Deploy EAP-TLS Wi-Fi certificates to ChromeOS devices with Smallstep and Google Workspace +html_title: Deploy EAP-TLS to Wi-Fi certificates +description: Configure EAP-TLS Wi-Fi certificates for Chromebooks using . Complete guide for iOS and macOS wireless security deployment at scale. +--- + +Smallstep can integrate with Google Workspace to exchange a SCEP challenge. The SCEP challenge is a shared secret that's used by devices to get a client certificate from Smallstep for a certificate-based Wi-Fi network or VPN server. + +## Prerequisites + +You will need: + +- A [Smallstep team](https://smallstep.com/signup) +- A Google Workspace tenant, and device management ability +- A ChromeOS device to enroll for testing + +## Before you begin + +First, follow the instructions in [Connect Google Workspace](./connect-google-workspace-to-smallstep.mdx) to sync your device inventory to Smallstep. + +## Step-by-step instructions + +### Create a SCEP Profile in Google Workspace + +*This section only applies if you want SCEP to be used to enroll clients.* + +1. In Smallstep, visit [Settings → Device Management](https://smallstep.com/app/?next=/settings/devices). Choose your existing Google Workspace integration. Copy the following values: + - SCEP URL + - SCEP Static Challenge +2. In Google Admin, visit [Devices → Networks → Secure SCEP](https://admin.google.com/ac/networks/scep). +3. Create a new SCEP configuration by clicking **Add Secure SCEP Profile**. + + The profile can be created at the organizational level, or within an Organization Unit (OU). For testing purposes, you can create a new OU and create the policy there. + +4. In the modal, configure the following: + - Check **Chromebook (Device)** + - Provide a name in **SCEP profile name**, e.g. `Smallstep` + - Set the **Subject name format** to **Fully distinguished name** + - Set **Common Name** to `${DEVICE_SERIAL_NUMBER}` + - Other properties can be filled as needed + - For **Subject Alternative Name**, choose **None** + - For **Key Usage**, choose + - Key encipherment + - Signing + - For Key Size, choose **2048** + - Set **Strict** attestation requirements + - Set the **SCEP server URL** to the SCEP URL obtained earlier. It should look like: + + ``` + https://.scep.smallstep.com/p/devices/google-workspace-integration- + ``` + + - For **Certificate validity period**, choose **1 year** + - For **Renew Within Days**, use **330** + - For **Extended key usage**, check **Client authentication** + - For **Challenge type**, use **Static**, and fill in the SCEP challenge obtained earlier + - **Template name** is for informational purposes and can be left empty. + - For **Certificate Authority**, Pick the name of the issuing (intermediate) CA for the Wi-Fi certificate. This is usually `Smallstep Devices Intermediate` +- For **Network type this profile applies to**, choose Wi-Fi + +### Confirmation + +After the SCEP Profile is configured, it will be applied to the device once policy is synchronized. You can force this by restarting the device. Reloading policies from the `chrome://policy` screen may not immediately force the SCEP policy to be evaluated for certificate issuance. From there, the configuration can be verified in several ways, including: + +- In the Smallstep UI, navigate to Certificate Manager → Certificates. A certificate should’ve been issued by the SCEP provisioner on the Devices authority. +- On the target device, visit `chrome://policy` in Chrome. Search for the `RequiredClientCertificateForDevice` policy. You should see an entry corresponding to the SCEP profile configured previously. +- On the target device, visit `chrome://settings/certificates` in Chrome. Under “Your certificates”, you should see a certificate matching the device serial number. Inspecting the certificate will revealed the issuer, which should be your Smallstep Devices CA.