Okta UID GID Sync Guide

How to sync UIDs and GIDs from Okta

Smallstep can automatically sync POSIX user and group IDs for your users from your identity provider.

To set up UID and GID syncing, we're going to need our SCIM app to map those attributes from your Okta user profiles.

This feature does not sync POSIX group membership mappings. Only UID and GID values are synced.

Step 1. Add UID and GID fields to your Okta user profile

Already have UID and GID fields for your users? Skip to Step 2.

  • Start at your Okta admin panel

  • Go to Directory → Profile Editor

  • Under Filters, select Okta. Choose Profile or User (default) here.

  • In the Profile Editor, choose + Add Attribute and add a uid attribute with data type "number".

    You may want to provide an Attribute Range minimum here, especially if you want to protect a range of IDs for service accounts on your hosts.

  • Save and Add Another, then create a GID attribute with data type "number".

    You may want to provide an Attribute Range minimum here, especially if you want to protect a range of IDs for service accounts on your hosts.

  • Save

Step 2. Add UID and GID fields to your Smallstep SCIM profile

  • Go to Directory → Profile Editor

  • Search and select your smallstep provisioning app profile.

  • Click the +Add Attribute button and add a uid attribute.

    Data type number

    Set the Display name, Variable name, and External name to uid

    External namespace urn:scim:smallstep:ssh:schema

    The attribute should be marked required, because any Okta user with an empty uid or gid value won't sync to Smallstep.

    Scope ☑ User personal

  • Save and Add Another, and add a gid attribute.

    Data type number

    Set the Display name, Variable name, and External name to gid

    External namespace urn:scim:smallstep:ssh:schema

    The attribute should be marked required because any Okta user with an empty uid or gid value won't sync to Smallstep.

    Scope ☑ User personal

  • Save

Step 3. Add mappings from Okta to your Smallstep provisioning app

  • Go to Applications → Applications

  • Choose your smallstep provisioning application

  • Go to the Provisioning tab

  • Under Attribute Mappings, you should see that uid and gid are not mapped.

  • Edit the mapping for uid:

    Select a type equal to Map from Okta Profile

    Choose the uid | number field.

    Apply on Create and update

    Save

  • Repeat for gid.

  • When you're finished, the mappings should look like this:

Step 4. Verify syncing with smallstep before going into production

  • These changes should trigger a sync of the UID and GID values to the smallstep dashboard.
  • If the values do not show up, try removing and re-adding the group assignments:
    • Open the smallstep provisioning app integration application within OKTA.
    • Go to the Assignments tab, select groups, and remove all the groups (remember these group names).
    • Wait until the users are removed from the smallstep dashboard (a few seconds).
    • Then re-add the groups using the assign button.
    • This will trigger a push, and you will see the new uid and gid values in the smallstep dashboard.

Send an email to support@smallstep.com.