Sync Users and Groups from your Identity Provider with SCIM
This feature is currently in Private Preview.
- Must be enabled by Tecton Support.
- Available for use with Okta and custom applications.
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​
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 areowner
,editor
,consumer
,operator
&viewer
. An example isorganization::editor
. - For roles that are not scoped to a resource, this is
organization
and no value for the ID. Possible role_ids areadmin
. An example isorganization::admin
. - For Secret Scopes, this is
secret_scope
and the secret scope's name. Possible role_ids aresecret_scope_writer
&secret_scope_reader
. An example issecret_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.
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:
-
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.
-
Log on to Okta’s admin dashboard as a Super Administrator (or Application Administrator if you already have a SAML application for Tecton).
-
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.
-
-
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.
-
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 examplehttps://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.
- 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
-
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.
-
-
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.
-
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:
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.
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.
-
In Okta, use the Profile Editor to create an attribute on the User Profile that your users' use (likely this is "User (default)").
- Go to Directory > Profile Editor, find & click the correct User profile and click the "Add Attribute" button.
- 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).
- Data type:
-
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).
- 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.
- 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
- Data type:
- 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
- Data type:
- 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
orRole 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
- Data type:
-
In Okta, use the Profile Editor to assign mappings of the user's attributes to the application's attributes.
- 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>".
- For the Admin role (i.e.
admin_role
), set the source to beArrays.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
). - For roles across all workspaces (e.g.
role_all_workspaces_editor
), set the source to beArrays.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
). - For all other roles that are scoped to a specific workspace (e.g.
role_workspace_prod_owner
) or secret scope, set the source to beArrays.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
).
-
Assign roles to your users.
- Find the user in Okta, click on the Profile tab and click the edit button.
- 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
).
- For the Admin role, add an entry for
-
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.