Okta Quickstart

Prerequisites

• An account on the smallstep platform
  Need one? Register here
• Okta Super Administrator privileges
• Okta Lifecycle 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.

Features

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

Overview

1. Create a new OIDC application in Okta, for single sign-on
2. Enter OIDC details into the Smallstep SSH UI
3. Add and configure the Smallstep application from the Okta Application Directory, for user sync via SCIM
4. Check logs to confirm users and groups are syncing to Smallstep SSH

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
   • click 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.

   • Assign any groups that will need either sudo and/or ssh access to hosts 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

7. 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. 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 by visiting the Users tab.

   

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:

5. Click "SAVE"
6. You've completed this portion of the setup.

Step 3. Add the Smallstep App Integration and Configure User Sync in Okta

• In the OKTA admin console, add the Smallstep application

  • Applications → Browse App Catalog

    • Search for 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"

• De-select "Automatically log in when user lands on login page"

• 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"

  

• Return to the Smallstep dashboard, or open a new browser tab and sign into the Smallstep dashboard: https://smallstep.com/app/[TEAM-NAME]

• Navigate to the Onboarding UI → Add Your Team → SCIM Details

• Copy Base URL, and API Token from Smallstep dashboard, and paste into Okta Provisioning form.

• In Okta, choose Test API Credentials. After successful verification, choose Save.

  

• Reload the provision tab

• Under Provisioning → Settings → To App, choose Edit and enable

  • Create Users
  • Update User Attributes
  • Deactivate Users

• Save.

  

• Assignments

  • Select the Assignments tab → Click Assign → Assign to Groups
  • Search by group → Assign any groups that will need either sudo and/or ssh access to hosts
  • Group names that contain a / are not supported in this release.

• Push Groups

  • Select the Push Groups tab → Push Groups → Find Groups By Name
  • Search for the same groups that will need either sudo and/or ssh access to hosts.
  • Save.
  • Repeat for each desired group.

Step 4. Sign in to the smallstep UI

• Select the Logs tab. You should see a list of success messages associated with SCIM-SYNC category items.

  

• Select the Users tab. If the onboarding dialog is open, press Esc to close.

• You should see your Users and Groups synced over from Okta.

OKTA Configuration Complete

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.
  • See our guide How to sync UIDs and GIDs from Okta.
• 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