Smallstep supports Identity Provider (IdP)-initiated Single Sign-On (SSO). This feature allows authorized employees to access the Smallstep dashboard in a moderated fashion, as an alternative to creating credentials in smallstep.

To setup access the dashboard using SSO you will need to:


  1. Configure an OAUTH client in your identity provider (IDP) and add a group of users to that client.
  2. Add the name, email, and admin type in the Dashboard Admins panel under the Settings menu in the Smallstep dashboard.

The email in the token provided by the IDP will be matched to the email in the Dashboard Admins list to authenticate access.


Identity Provider Instructions

G Suite

STEP 1. CREATE AN OAUTH CLIENT ID

Configure the OAuth Consent Screen

  1. In the Google Cloud Console, visit Configure the OAuth Consent Screen
  2. Choose User Type: Internal
  3. Create
  4. Now give your application a name, like Smallstep SSO
  5. Update the support email address, if needed
  6. Save

STEP 2. CREATE AN OAUTH Credential

  1. Visit Create an OAuth Credential
  2. Choose Application type: Web Application
  3. Name it Smallstep SSO
  4. Add an Authorized redirect URI https://api.smallstep.com/auth/openid/callback
  5. Create
  6. Copy the Value of Your Client ID and Your Client Secret and save them.

STEP 3. ENTER YOUR OIDC SETTINGS INTO THE SMALLSTEP SSO UI

  1. Open a new browser tab and log in at https://smallstep.com/app/[TEAM-NAME]/settings
  2. In the Dashboard SSO page click “GET STARTED”
  3. Select G SUITE as your OpenId provider and enter the client id and client secret.
  4. enter the following string for the configuration endpoint https://accounts.google.com/.well-known/openid-configuration
  5. Click CREATE

STEP 4. Add SSO dashboard users to the SMALLSTEP UI

Dashboard admins need to be added to both the OpendId app and to the smallstep dashboard.

  1. Open a new browser tab or login to https://smallstep.com/app/[TEAM-NAME]/settings/admins/add
  2. Enter the users information and click CREATE

Open a new browser tab or login to https://smallstep.com/app/[TEAM-NAME]/settings/admins/add

Azure

STEP 1. CREATE AN OAUTH OIDC App

  1. Create an App Registration
  2. Give your app a name like Smallstep SSO
  3. Under Supported account types select Accounts in this organizational directory only
  4. Click Register
  5. Now go back to your browser and go to App Registrations. and select the app your just created note the Application (client) ID and Directory (tenant) ID
  6. Add a redirect URI, select Authentication from the left hand navigation
  7. Under Platform Configurations click Add a Platform
  8. Select Web Application
  9. Add a redirect URI  ****https://api.smallstep.com/auth/openid/callback
  10. Select ID tokens (used for implicit and hybrid flows)
  11. Configure
  12. Add a Client Secret, select  Certificates & Secrets from the left hand navigation
  13. Click New Client Secret and give it a name like Smallstep SSO and expiration
  14. Add
  15. Save the Client Secret, Application (client) ID, and  Directory (tenant) ID from step 6.

STEP 2. ENTER YOUR OIDC SETTINGS INTO THE SMALLSTEP SSO UI

  1. Open a new browser tab and log in at https://smallstep.com/app/[TEAM-NAME]/settings
  2. In the Dashboard SSO page click “GET STARTED”
  3. Select Azure as your OpenId provider and enter the client id and client secret.
  4. For the configuration endpoint, enter the following string replacing {tenant} with your applications Directory (tenant) ID: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
  5. Click CREATE

STEP 3. Add SSO dashboard users to the SMALLSTEP UI

Dashboard admins need to be added to both the OpendId app and to the smallstep dashboard.

  1. Open a new browser tab or login to https://smallstep.com/app/[TEAM-NAME]/settings/admins/add
  2. Enter the users information and click CREATE

Okta

STEP 1. CREATE OKTA OIDC APPLICATION (Instructions verified on 1/25/2023)

  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 Web Application for the Application type.
  4. Give it a name like smallstep-sso
  5. Under Sign-in redirect URIs, replace the default localhost with: https://api.smallstep.com/auth/openid/callback
  6. Under Assignments, select "Skip group assignment for now."
  7. Click save to continue to the next steps
  8. Go to the General tab → Note the Client Id and Client Secret.
  9. Click edit next to the General Settings section
  10. Under Grant Type select the Implicit (hybrid) radio button.
  11. Select the Allow ID Token with implicit grant type radio button.
  12. Save changes

STEP 1. Assign Users

  1. At the top of the Page, select the Assignments tab.
  2. Select the blue Assign button  → Assign People to add the users you want to have access to the Smallstep dashboard
  3. Go Back to the top of the page, select the General tab, and note the client id and secret for the next step.

STEP 3. ENTER YOUR OIDC SETTINGS INTO THE SMALLSTEP SSO UI

  1. Open a new browser tab and log in at https://smallstep.com/app/[TEAM-NAME]/settings
  2. In the Dashboard SSO page click “GET STARTED”
  3. Select Okta as your OpenId provider and enter the client id and client secret.
  4. For the Configuration Endpoint, enter the following string replacing {your Okta domain} with your existing OKTA domain: https://{your Okta domain}/.well-known/openid-configuration
  5. Click CREATE

STEP 4. Add SSO dashboard users to the SMALLSTEP UI

Dashboard admins need to be added to both the OIDC app and to the smallstep dashboard.

  1. Open a new browser tab or login to https://smallstep.com/app/[TEAM-NAME]/settings and click the "+ ADD ADMIN" button at the top of the settings page.
  2. Enter the users information and click CREATE