1. Send your Okta tenant URL to Smallstep.

   You will receive a few configuration values from us for configuring an OpenID Connect IdP.

2. In Okta’s admin portal, visit Security → Identity Providers and choose Add identity provider.

3. Choose OpenID Connect IdP, and choose Next.

   <aside> 👉

   If you don’t see OpenID Connect IdP in the list of available IdPs, open a support case with Okta and ask them to enable the GENERIC_OIDC_IDP feature flag for your Okta tenant.

   </aside>

4. Configure the OpenID Connect IdP:

   • For Name, use Smallstep
   • For IdP Usage, select Factor only
   • Populate Client ID, Client Secret, Issuer, Authorization endpoint, Token endpoint, and JWKS endpoint with the values you received from Smallstep.

5. In Okta admin portal, visit Security → Authenticators and choose Add authenticator.

   Select IdP Authenticator

   Select the Smallstep IdP you just created

6. In Okta admin portal, visit Security → Authentication Policies.

   Here you can adjust the policy rules for the Smallstep Authenticator, as needed.

   On a fresh Okta tenant, the default policy is “Any two factors.” By adding the Smallstep Authenticator in the previous step, Okta makes it available as an optional second factor.

   Choose your default policy, and confirm that Smallstep is listed as an additional factor type.

7. In Smallstep, create a new Browser account

   • Under Browser Identity Settings, for Include Hostname, add the Issuer URL you received from Smallstep, eg. https://example.id.smallstep.com.
   • It is safe to use a longer lifetime for this certificate, since the private key will be hardware bound. Choose a lifetime up to 1 year.
   • Choose Save Account

8. Now let’s test your setup. Start the Smallstep App and sign in.

9. Ensure your browser has a current certificate for the authority from Step 2. The first email SAN in the cert should be your Okta login username. You’ll see the certificate in the Smallstep app.

10. Sign into an app using the authentication policy you created. Choose the Smallstep IdP as your second factor when signing in. If you see a client certificate selection dialog, select your Smallstep certificate.

What if I have multiple roots?

If you want multiple CAs to be trusted by your Smallstep factor IdP—whether they are Smallstep managed CAs or not—construct a PEM bundle of trusted roots and send it to Smallstep and we’ll update your IdP.

ro-to-smallstep/#create-an-api-client-in-jamf-pro