Okta Quickstart


You will need:

  • An account on the smallstep platform
    Need one? Register here
  • Okta Super Administrator privileges
  • Okta Universal Directory Subscription
  • Okta Advanced Lifecycle Management Subscription
  • Okta API Access Management Subscription
  • Two (or more) Okta groups:
    • A group whose members should be allowed to SSH (we'll refer to this as the ssh group, but you can call it whatever you want)
    • A group whose members should be allowed to sudo (we'll refer to this as the sudo group, but you can call it whatever you want)
    • You can use existing groups, or create new ones (Directory → Groups → Add Group)
    • Make sure you add users that should be allowed to ssh/sudo to the respective groups (Directory → Groups → select group → Manage People)
    • For more granular access, you can create multiple groups and grant access to a subset of smallstep managed hosts.


The following provisioning features are supported:

  • Push Groups and New Users
    • New users created through OKTA will also be created in the third party application.
  • Push Profile or Group Updates
    • Updates made to the user's profile through OKTA will be pushed to the third party application.
  • Push User Deactivation
    • Deactivating the user or disabling the user's access to the application through OKTA will deactivate the user in the third party application.
    • Note: For this application, deactivating a user means removing access to login, but maintaining the user's ssh access information as an inactive user.
  • Reactivate Users
    • User accounts can be reactivated in the application.

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 → Add Application → Create New App → Platform: “Native app” → Create

  3. You'll see the Create OpenID Connect Integrations page.

    • General Settings
      • Application name: smallstep-oidc
    • Configure OpenID Connect
      • Login redirect URIs:
    • Save

  4. Go to the General tab → Scroll down to "Client Credentials" and choose "Edit"

    • Select "Use Client Authentication" radio button
    • Save

  5. Go to the Assignments tab.

    • Assign the sudo and ssh groups to the smallstep-oidc app:
      • Assignments → Assign → Assign to Group → Click "Assign" for ssh
      • Assignments → Assign → Assign to Group → Click "Assign" for sudo
      • Repeat this process for any other groups you created for controlling SSH/sudo access
  6. 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 SSH UI

  1. Open a new browser tab and log in to Smallstep: https://smallstep.com/app/[TEAM-NAME]

  2. Navigate the Onboarding Dialog. If the dialog is not open, you can relaunch it from the "Resources" page.

  3. Copy and paste your Client ID and Client Secret from Okta.

  4. 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


  6. You've completed this portion of the setup.

Step 3. Configure User Sync in Okta

  • Add the Smallstep Application

    • Applications → Add Application → Search

      • Search: Smallstep

      • Select the Smallstep App:

  • Click "Add"

  • Select "Do not display application icon to users"

  • Select "Do not display application icon in the Okta Mobile App"

  • Click Next

  • Select "Administrator sets username, user sets password"

  • Application username format: "Okta username prefix"

  • Update application username on "Create and update"

  • Done

  • Provisioning

    • Select the "Provisioning" tab
    • Click "Configure API Integration" and select the checkbox next to "Enable API integration"

  • Open a new browser tab and sign into the Smallstep UI: https://smallstep.com/app/[TEAM-NAME]

  • Navigate to Set Up User Sync tab, copy Base URL, and API token from Smallstep UI and Paste into Okta Provisioning form.

  • Click Save

  • Under Provisioning "To App" click "edit" and enable - Create Users - Update User Attributes - Deactivate Users

  • click Save

  • Assignments

    • Select the "Assignments" tab → Click "Assign" button → "Assign to Groups"
    • Search by group → assign sudo and ssh groups (and any other groups you created for controlling SSH and sudo access)
    • Group names that contain a / are not supported in this release.
  • Push Groups

    • Select the "Push Groups" tab → Click "Push Groups" button → "Find Groups By Name"
    • Search for the same sudo group by name.
    • Click "Save"
    • Repeat for the ssh group.

Step 4. Sign in to the smallstep UI

Sign in at https://smallstep.com/app/[Team ID]

You should see your Okta directory with users and groups synced.

Troubleshooting Tips

  • Initial activation of Okta OIDC provisioning in Smallstep SSH requires entering your Client ID, Client Secret, and base domain of your Okta instance. Contact smallstep support with any questions | support@smallstep.com
  • UIDs and GIDs. By default, Smallstep will auto-assign POSIX UIDs and GIDs for your users. Alternatively, you can sync POSIX UIDs and GIDs values from your Okta directory to Smallstep.
  • If you are having trouble synchronizing users or groups, it's always recommended to resynchronize the information manually:
    • Applications → Smallstep → Push Groups → Find Group → "Push Now'

  • When users are deactivated in Okta, they will be deactivated in Smallstep. Users will not be able to SSH to servers, but their user accounts will remain on smallstep managed hosts. To permanently delete user data on smallstep managed hosts, contact Smallstep Support | support@smallstep.com

Unsubscribe anytime. See our privacy policy.