Sync Users and Groups from your Identity Provider with SCIM

Private Preview

This feature is currently in Private Preview.

This feature has the following limitations:

• Must be enabled by Tecton Support.
• Available for use with Okta and custom applications.

If you would like to participate in the preview, please file a feature request.

Tecton supports the System for Cross-domain Identity Management (SCIM) open standard, allowing you to control provisioning of users, service accounts, groups, group memberships and access controls from within your Identity Provider. By leveraging Tecton's SCIM API, you can manage onboarding and guarantee off-boarding through your existing processes.

About SCIM and Tecton's SCIM Support

SCIM is designed to make managing user identities in cloud-based applications and services easier. Tecton supports SCIM 2.0. SCIM defines an HTTP RESTful API and schema for common resources. SCIM APIs are called by a SCIM Client (typically an Identity Provider) to provision/update/deprovision resources in the SCIM Server (typically a Service Provider - Tecton in this case). Identity Providers like Okta and Azure Entry ID have built-in support for calling SCIM APIs and can automatically sync changes to users & groups into downstream applications via their SCIM APIs. You can also build your own custom integrations and call Tecton's SCIM APIs directly.

Tecton's SCIM API supports managing:

• Users
• Groups
• Service Accounts
• Group memberships
• Role assignments

Managing Role Assignments

note

Managing role assignments in the SCIM APIs is optional. Contact support to disable roles management from the SCIM APIs for users, groups and/or service accounts.

Role assignments are viewable and editable directly on Users, Groups and Service Accounts. Role assignments are expressed as a string per assignment (e.g. workspace:prod:owner). They have the format <resource_type>:<resource_id>:<role_id>, where resource_type and resource_id define on which resource the role is assigned.

• For Workspaces, this is workspace and the workspace's ID (e.g. workspace:dev:viewer).
• For roles assigned over all workspaces, this is organization and no value for the ID. Possible role_ids are owner, editor, consumer, operator & viewer. An example is organization::editor.
• For roles that are not scoped to a resource, this is organization and no value for the ID. Possible role_ids are admin. An example is organization::admin.
• For Secret Scopes, this is secret_scope and the secret scope's name. Possible role_ids are secret_scope_writer & secret_scope_reader. An example is secret_scope:my_scope:secret_scope_writer.

Prerequisites

Your SCIM client (typically your Identity Provider) must have network access to connect to your Tecton account in order to call the SCIM APIs. For example, Okta does not support AWS PrivateLink, and so will not work if your Tecton account restricts traffic to AWS PrivateLink only. Contact Tecton if you would like to configure an IP Allowlist to allow traffic from your IdP (example).

Using Okta

Okta can be configured to control users, groups, group memberships and role assignments in your Tecton instance(s). In your Okta organization, you'll use an SAML application with SCIM enabled to drive the integration. As changes to users, groups, etc. occur in Okta, Okta will call Tecton's SCIM APIs to sync changes to Tecton.

note

Okta does NOT support:

• Managing Service Accounts (Okta only supports syncing users and groups via SCIM, not applications)
• Managing Groups' description, idpMappingNames nor role assignments. Okta's Group Push Mapping only supports the Group Display Name, along with Group Membership sync (see this Okta Knowledge Base article). Because of this, you may want to have Tecton disable roles management from the SCIM APIs for groups.

For more information, please refer to Okta’s overview of SCIM and to Okta's suggested Typical workflow for adding provisioning to an existing app integration.

Configuring Okta

To set up a SCIM integration from your Okta organization to Tecton:

1. Create or have handy an API key generated from a Tecton Service Account with admin privileges. If needed, you can create a service account via either the Tecton CLI or the web UI. See this docs page for more information on how to create a Tecton Service Account.

2. Log on to Okta’s admin dashboard as a Super Administrator (or Application Administrator if you already have a SAML application for Tecton).

3. Create or use a SAML 2.0 application to use SCIM.

   • If you have an existing SAML application for Tecton, you can use it for SCIM too. Open your SAML 2.0 Tecton application in Okta under “Applications” and navigate to the “General” tab.

   • Otherwise, create a SAML 2.0 application to use SCIM with Tecton.

     • See this Okta docs page to create a SAML 2.0 “custom integration” application for use with Tecton.
     • If you are only using this application for SCIM, ignore the SAML settings and check the "Do not display application icon" boxes to hide the application. Otherwise, see this Tecton docs page for Tecton's SAML configuration and contact Tecton Support to connect the application to Tecton.

4. Click “Edit” in the App Settings box and click “Enable SCIM provisioning”.

   • After enabling, you should see a new tab at the top of the application window called “Provisioning” appear.
   

5. Navigate to the Provisioning tab, where you should be presented with a section entitled “SCIM Connection”. Note that this corresponds to the “Integration” tab at the left hand navigation menu. Click “Edit” and fill in these options:

   • SCIM connector base URL: This should be your Tecton instance’s hostname appended with the URL path /api/scim/v2 , for example https://mycompany.tecton.ai/api/scim/v2.

   • Unique identifier field for users: userName

   • Supported provisioning actions: You can select the relevant options below as desired. Most customers may want to leave “Import New Users and Profile Updates” unchecked, but some may want to import Tecton Groups. Please consult this Okta docs page for more information on these options.

     • NOTE: You may be presented with the error “Bad Request” when attempting to Save the SCIM Connection if “Import Groups” is checked. This is an Okta error due to the SELECTIVE_APP_IMPORT_PLATFORM feature flag not enabled. Contact your Okta account executive to enable it. In the meantime, you can select all of the options except Import Groups to continue.

   • Authentication Mode: Select “HTTP Header”

   • HTTP Header / Token field: Enter the API key corresponding to a Tecton service account with admin privileges on this Tecton instance. Your Okta IdP will connect to your Tecton instance with this token in order to manage users and groups.

   

6. Click “Test Connector Configuration” and you should see all green checkmarks. Save this connection.

   • At this point, you’ll now see three options in the Settings nav bar to the left. You can always return to the SCIM Connection settings above by clicking the “Integration” menu item.

7. Under the Provisioning Tab “To App” section, click “Edit” in the “Provisioning to App” section.

   • Enable all options except Sync Password, i.e.: Create Users, Update User Attributes, and Deactivate Users. Click “Save”.

     

Configuring Okta for users' role assignments

To manage a user's role assignments, we recommend configuring Okta as follows:

note

References to instance name below mean the sub-hostname for your tecton instance. For example, if your tecton url is https://example.tecton.ai, then your instance name is example. If there are multiple words, then use the same separator as written in the placeholder. For example, the <instance_name> for https://example-staging.tecton.ai is example_staging (note the use of an underscore as the separator, rather than a dash). This is the instance name used in the examples below.

note

There are some parts below using _ as separators and others using :. Tecton uses : as the separator in role assignment values but Okta does not permit colons in the "External name" expressions so _ is used instead.

1. In Okta, use the Profile Editor to create an attribute on the User Profile that your users' use (likely this is "User (default)").

   1. Go to Directory > Profile Editor, find & click the correct User profile and click the "Add Attribute" button.
   2. Set the following properties on the attribute and save it:
      • Data type: string array.
      • Display name: Tecton <instance name> Roles (e.g. Tecton Example Staging Roles).
      • Variable name: tecton_<instance_name>_roles (e.g. tecton_example_staging_roles).
      • Description: Tecton roles for <instance name> that the SCIM integration will set on the user.
      • After saving, ensure that the "User permission" is either "Hide" or "Read-only" (if it is "Read-Write", then each user can set the value and assign any Tecton roles they want for themselves).

2. In Okta, use the Profile Editor to add attributes on the Application configured for SCIM with Tecton. There will be one attribute on the application per role in Tecton (unfortunately, Okta does not allow using a single Attribute for this).

   1. Go to Directory > Profile Editor, find & click the correct Application profile (search for the application you created above in Configuring Okta). Click the "Add Attribute" button for each Tecton role you wish to be able to assign.
   2. For the "Admin" role, set the following properties on the attribute and save it:
      • Data type: string.
      • Display name: Role Admin.
      • Variable name: role_admin.
      • External name: roles.^[type=='organization__admin'].value (note that there are two underscores between organization and admin).
      • External namespace: urn:ietf:params:scim:schemas:core:2.0:User.
      • Description: Tecton Admin role (aka Admin account type).
      • Attribute type: Personal
   3. For roles across all workspaces, set the following properties on the attribute and save it. (Create one for Owner, Editor, Consumer, Operator and Viewer):
      • Data type: string.
      • Display name: Role All Workspaces <role name> (e.g. Role All Workspaces Editor).
      • Variable name: role_all_workspaces_<role_name> (e.g. role_all_workspaces_editor).
      • External name: roles.^[type=='organization__<role_name>'].value (e.g. roles.^[type=='organization__editor'].value) (note that there are two underscores between organization and the role name).
      • External namespace: urn:ietf:params:scim:schemas:core:2.0:User.
      • Description: Tecton editor role in all workspaces.
      • Attribute type: Personal
   4. For all other roles that are scoped to a specific workspace or secret scope, set the following properties on the attribute and save it (create one for each role in each workspace and each role in each secret scope):
      • Data type: string.
      • Display name: Role <resource type> <resource name> <role name> (e.g. Role Workspace Prod Owner or Role Secret Scope Testing Manager).
      • Variable name: role_<resource_type>_<resource_name>_<role_name> (e.g. role_workspace_prod_owner).
      • External name: roles.^[type=='<resource_type>_<resource_name>_<role_name>'].value (e.g. roles.^[type=='workspace_prod_owner'].value) (Note that the variable name can not contain hyphens/dashes, use underscores instead).
      • External namespace: urn:ietf:params:scim:schemas:core:2.0:User.
      • Description: Tecton owner role in prod workspace.
      • Attribute type: Personal

3. In Okta, use the Profile Editor to assign mappings of the user's attributes to the application's attributes.

   1. Go to Directory > Profile Editor, find & click the correct Application profile (search for the application you created above in Configuring Okta). Click the "Mappings" button and then click on the tab for "Okta User to <application name>".
   2. For the Admin role (i.e. admin_role), set the source to be Arrays.contains(user.tecton_<instance_name>_roles, "organization::admin") ? "organization::admin" : null (e.g. Arrays.contains(user.tecton_example_staging_roles, "organization::admin") ? "organization::admin" : null).
   3. For roles across all workspaces (e.g. role_all_workspaces_editor), set the source to be Arrays.contains(user.tecton_<instance_name>_roles, "organization::<role_name>") ? "organization::<role_name>" : null (e.g. Arrays.contains(user.tecton_example_staging_roles, "organization::editor") ? "organization::editor" : null).
   4. For all other roles that are scoped to a specific workspace (e.g. role_workspace_prod_owner) or secret scope, set the source to be Arrays.contains(user.tecton_<instance_name>_roles, "<resource_type>:<resource_name>:<role_name>") ? "<resource_type>:<resource_name>:<role_name>" : null (e.g. Arrays.contains(user.tecton_example_staging_roles, "workspace:prod:owner") ? "workspace:prod:owner" : null).

4. Assign roles to your users.

   1. Find the user in Okta, click on the Profile tab and click the edit button.
   2. In the Tecton <instance name> Roles field, click the "Add Another" button and add an entry for each role you want assigned to them in Tecton:
      • For the Admin role, add an entry for organization::admin.
      • For roles across all workspaces, add entries like organization::<role_name> (e.g. organization::editor).
      • For all other roles that are scoped to a specific workspace, add entries like <resource_type>:<resource_name>:<role_name> (e.g. workspace:prod:owner).

5. Verify: Ensure the user is assigned the application and provisioning is enabled. Their roles in Tecton will be updated based upon the above attributes, attribute mapping and SCIM provisioning.

Provisioning and Syncing

• Import: You can now navigate to the “Import” tab at the top of the Application, and click “Import Now”. This will import all users and their profiles from your Tecton instance into your Okta IdP if they haven’t already been imported. If you’ve enabled “Import Groups”, it will also import any Tecton groups that were created on the instance.

• Assignments: Here you can assign users and groups as normal with applications. You probably have this set up with your existing Tecton application, and you can make any changes necessary here as needed.

• Push Groups: The “Push Groups” tab also appears when you enable SCIM provisioning. With Push Groups, you can push your Okta groups assigned to your Tecton application to Tecton, including group membership information. If you’ve already assigned permissions to the group inside Tecton, any members of the group will receive that groups’ permissions, in addition to permissions they may have been assigned manually or via other groups they are members of. See this Okta docs page for more information on Push Groups and its options.

  • Click the Push Groups button at the top of this tab, and click for example “Find groups by name” where you can manually enter groups to be pushed to Tecton.

  • Select either “Create Group” if the group does not exist in Tecton, or “Link Group” if it does and enter the corresponding group name inside Tecton.

HTTP API Reference

Tecton's SCIM HTTP API Reference can be found here.

Limitations

SCIM defines an optional PATCH method on resources that Tecton does not implement. Some identity providers (e.g. Azure Entry ID) use PATCH instead of PUT for updates of users/groups and therefore these SCIM Clients will not be able to sync updates.

FAQ

How do SSO & SCIM differ?

SSO and SCIM tackle different problems (with some overlap) and usually go hand-in-hand. Single Sign-on (SSO) is used to authenticate users, delegating authentication from the application to the user's Identity Provider. SCIM is used for managing identities in applications and services and allows for delegating provisioning/deprovisioning to an Identity Provider. While SSO supports just-in-time provisioning to create a new user in an application on first sign-in, SCIM allows the provisioning to happen earlier, when the user is assigned the application. SCIM also supports deprovisioning, while SSO does not.