Merge pull request #446 from smallstep/carl/okta-usersync

Okta User sync docs

Author: tashian

manifest.json

@@ -76,6 +76,15 @@
           ]
         },
         {
+          "title": "Add Users to Smallstep",
+          "routes": [
+            {
+              "title": "Sync Okta Users (SCIM)",
+              "path": "/tutorials/sync-okta-users-to-smallstep.mdx"
+            }
+          ]
+         },
+         {
           "title": "Smallstep for WPA-Enterprise Wi-Fi",
           "routes": [
             {

tutorials/sync-okta-users-to-smallstep.mdx

@@ -0,0 +1,132 @@
+---
+updated_at: October 23, 2025
+title: Sync Okta Users to Smallstep
+description: Smallstep Okta User SCIM synchronization
+---
+
+### Prerequisites
+
+You will need:
+
+* An account on the Smallstep platform  
+  Need one? [Register here](https://smallstep.com/signup)
+* Okta Super Administrator privileges
+* Okta Lifecycle Management Subscription
+
+### Features
+
+The following provisioning features are supported:
+
+* Push Groups and New Users
+  * New users created through Okta will also be created in Smallstep.
+* Push Profile or Group Updates
+  * Updates made to the user's profile through Okta will be pushed to Smallstep.
+* Push User Deactivation
+  * Deactivating the user or disabling the user's access to the application through Okta will deactivate the user in Smallstep.
+  * Note: For this application, deactivating a user means removing access to login, but the user's devices will not be affected.
+* Reactivate Users
+  * User accounts can be reactivated in the application.
+
+## Overview
+
+In this quickstart, we will:
+
+1. Create a new OIDC application in Okta, for single sign-on
+2. Enter OIDC details into the Smallstep UI
+3. Add and configure the Smallstep application from the Okta Application Directory, for user sync via SCIM
+4. Confirm users and groups are syncing to Smallstep
+
+## Step By Step Instructions
+
+### **Step 1. Create Okta OIDC Application**
+
+1. Start at your Okta admin dashboard (access via "Admin" button next to "+ Add Apps" after successful log in)
+2. Go to Applications → Create App Integration
+3. In the pop up select "OIDC - OpenID Connect" as the sign-in method and specify "Native Application" for the Application type.
+4. New Native App Integration Page
+   * App integration name: `smallstep-oidc`
+   * Sign-in redirect URIs: `http://127.0.0.1:10000`
+   * Select "Skip group assignment for now"
+   * All other value leave as default
+   * **Save**
+5. Go to the **General** tab → Scroll down to "Client Credentials" and choose "Edit"
+   * Select "Use Client Authentication" radio button
+   * **Save**
+6. Go to the **Assignments** tab.
+7. Assign any groups that will need access to Smallstep to the `smallstep-oidc` app
+8. Go back to **General** tab and scroll down to "Client Credentials." You'll refer to these values in the next step.
+
+### Step 2. Enter your OIDC Details into the Smallstep dashboard
+
+1. Start at [Connect an Okta IdP](https://smallstep.com/app/?next=/settings/users/identity-providers/okta/connect)
+2. Copy and paste your **Client ID** and **Client Secret** from Okta.
+3. The **Configuration Endpoint** is derived from your Okta domain. Fill your Okta domain into the following URL:
+  
+    `https://{your Okta domain}/.well-known/openid-configuration`
+
+     This is your **Configuration Endpoint**. For example, if you normally sign into Okta at `https://example.okta.com/`, then your configuration endpoint is `https://example.okta.com/.well-known/openid-configuration`
+
+4. Select how you'd like to sync users from Okta.
+5. **Save**
+6. After saving, you will see a Base URL for SCIM sync, and a SCIM token. Copy these values for the next step.
+
+### Step 3. Add the Smallstep App Integration and Configure User Sync in Okta
+
+1. In the Okta admin console, add the Smallstep application
+  * Applications → Browse App Catalog
+    * Search for `Smallstep`
+    * Select the Smallstep app.
+2. Click "Add"
+
+      ![](/graphics/quickstart/okta-app-add.png)
+
+3. Select "Do not display application icon to users"
+4. Select "Do not display application icon in the Okta Mobile App"
+5. De-select "Automatically log in when user lands on login page"
+6. Choose Next
+
+      ![](/graphics/quickstart/okta-app-signon.png)
+
+7. Select "Administrator sets username, user sets password"
+8. Application username format: "Okta username prefix"
+9. Update application username on "Create and update"
+10. Done
+
+### Configure Provisioning
+
+Next, we'll turn on SCIM provisioning of users from Okta.
+
+1. Select the "Provisioning" tab
+2. Click "Configure API Integration" and select the checkbox next to "**Enable API integration**"
+
+    ![](/graphics/quickstart/okta-enable-api.png "Enable API")
+
+3. Paste your **Base URL** for SCIM sync and **API Token** (SCIM Token) into Okta Provisioning form.
+4. In Okta, choose **Test API Credentials**. After successful verification, choose **Save**.
+
+   ![](/graphics/quickstart/okta-api-auth.png "API Auth")
+
+5. Reload the provision tab
+6. Under Provisioning → Settings → To App, choose **Edit** and enable the following:
+   * Create Users
+   * Update User Attributes
+   * Deactivate Users
+7. Save.
+8. Configure Assignments:
+   * Select the **Assignments** tab → Click **Assign**  → **Assign to Groups**
+   * Search by group → Assign any groups that will use Smallstep
+   * Group names that contain a `/` are not supported
+9. Configure Push Groups:
+   * Select the **Push Groups** tab → **Push Groups** → **Find Groups By Name**
+   * Search for the same groups that will use Smallstep
+   * Save.
+   * Repeat for each desired group.
+
+## Confirmation
+
+Back in Smallstep, go to [Users](https://smallstep.com/app/?next=/users).
+You should see your Okta users here.
+
+When users are deactivated in Okta, they will be deactivated in Smallstep.
+Their devices will remain in Smallstep.
+