Dashboard How-Tos
      Back to home
      1. Smallstep Knowledge Base
      2. Documentation
      3. Dashboard How-Tos

      Set up Dashboard access using SSO

      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 set up access to 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.

      While we do our best to ensure that configuration instructions between Smallstep and third-party apps are up-to-date, the instructions may have changed. If you find any errors or changes to these instructions, feel free to let us know.

      Identity Provider Instructions

      The following instructions cover Google Workspace (G Suite), OKTA, and Azure AD (AZAD)

      Google Workspace (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 user's information and click CREATE

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

      Azure AD (AZAD)

      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 you 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 the smallstep dashboard.

      1. Open a new browser tab or login to https://smallstep.com/app/[TEAM-NAME]/settings/admins/add
      2. Enter the user's 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 login)
      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 2. 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 log in to https://smallstep.com/app/[TEAM-NAME]/settings and click the "+ ADD ADMIN" button at the top of the settings page.
      2. Enter the user's information and click CREATE