In this article, we will review information related to System for Cross-domain Identity Management (SCIM) for your organization. SCIM allows organizations to manage internal CodeSignal users, role assignments and team assignments directly from their identity providers.

We will cover:

• Introduction
• Prerequisites
• Configuration steps
• Maintenance
• Appendices

Introduction

The purpose of this integration guide is to:

• Act as a Centralized Source of Information: This document is the definitive guide for understanding and executing the integration between CodeSignal and your identity provider’s SCIM. It ensures that all stakeholders have a consistent reference point.

• Facilitate Smooth Implementation: By detailing each step of the integration process, this guide aims to prevent common pitfalls, reduce the learning curve, and minimize errors.

• Enable Scalability: As more teams or individuals in an organization need to implement or understand this integration, having a structured guide ensures they can do so without repeatedly seeking expert assistance.

• Promote Best Practices: By outlining recommended configurations, considerations, and maintenance procedures, the guide ensures that users follow best practices that maximize efficiency.

• Serve as a Training Tool: New team members or those unfamiliar with either of the platforms can utilize the guide as a training resource, ensuring consistent knowledge transfer.

• Encourage Feedback and Continuous Improvement: The document can act as a foundation for gathering user feedback, leading to iterative improvements in both the integration process and the guide itself.

Overview: CodeSignal

CodeSignal is a comprehensive technical assessment platform that assists companies in evaluating and certifying the coding skills of job candidates. Through its suite of assessment tools, ranging from coding challenges to simulated real-world tasks, CodeSignal provides a standardized way for recruiters and hiring managers to gauge the technical abilities of applicants objectively, ensuring a more efficient and data-driven hiring process.

CodeSignal offers products to assist with pre-screen assessments and live, peer-coding interviews. Additionally, it provides analytics data to assist with overall cost reduction, enhancing the candidate experience, and improving processes.

Overview: SCIM

The System for Cross-domain Identity Management (SCIM) is an open standard that plays a crucial role in the automated exchange of user identity information between different identity domains. It is designed to simplify and streamline the management of user identities and their associated attributes across various systems and services. SCIM helps organizations manage user identities efficiently through identity and access management (IAM) systems. SCIM is commonly used in scenarios where identity information needs to be synchronized between different systems, such as between an identity provider (IdP) and a service provider (SP), including user provisioning, de-provisioning, and updates.

Key aspects of SCIM include:

Standardization: SCIM provides a standardized way to represent and exchange identity information, ensuring interoperability between different systems and platforms. This standardization helps organizations integrate various identity management solutions seamlessly.

RESTful Protocol: SCIM is based on a Representational State Transfer (REST)ful protocol, utilizing HTTP methods (such as GET, POST, PUT, DELETE) for communication. This makes it lightweight, scalable, and easy to implement.

User Schema: SCIM defines a common user schema that includes standard attributes like username, email address, and display name. The standardization of attributes ensures consistency across different systems, making it easier to map and synchronize user data.

Endpoints and Operations: SCIM defines endpoints for user provisioning, allowing systems to create, read, update, and delete user accounts. These operations are crucial for identity lifecycle management.

Prerequisites

To integrate the two solutions, you will need the following:

User Accounts

CodeSignal

• An account with a Company Admin role. If you need to use an account with more restrictive permissions, please review our support articles below or contact CodeSignal support for guidance on the minimum required permissions for the various tasks you will need to carry out.
  • User Roles and Permissions Management
  • Creating and managing Custom Roles
  • Managing your members
  • Segmenting Your Company's User Accounts with Teams

Your organization’s identity provider

• An account with admin permissions. 

System Requirements

CodeSignal

• The solution is 100% SaaS. No on-premise or cloud resources are required. Access is supported through standard browsers. The list of supported browsers can be found in this Support Article.
• Enabled SSO through your company’s settings. Instructions on how to do so can be found in this Support Article. 

For Group (Team) Management [Optional]

It is possible to manage groups (teams, as they are known in CodeSignal) using SCIM 2.0. This is optional, but if you will be using group management via SCIM you will need to ensure the following:

• Ensure that your identity provider (IdP) supports SCIM 2.0.
• Verify that your IdP has configurations set up for managing groups through SCIM.
• In CodeSignal, go to the Organization Settings page and click on the SCIM settings section. Enable group management via SCIM 2.0 for your organization.

Configuration Steps

(Recommended) Option 1: Using the default role assignment

This option is our most popular and most seamlessly supported way to use SCIM. All users will be provided with the default role unless they require higher permissions. 

Step 1: Retrieve your Bearer Token from CodeSignal

1. Log in to your company's CodeSignal account as a Company Admin.
2. Click My Company Settings in the drop-down menu at the top right of your screen.
3. In the SSO tab, ensure that the Enable SSO toggle is on.
4. Navigate to the User Provisioning tab and toggle on Enable SCIM.
5. Click the Create button to generate a SCIM Token. Copy this token.
6. In the Default Role drop-down menu, choose the default role you'd like to assign to new users: Interviewer, Manager, or Company Admin.
7. To create a new role, you can find more information in this Support Article.

Step 2: Enable SCIM API integration in your identity provider

If your identity provider does not have a CodeSignal marketplace application, you will need the following information to enable the SCIM API integration in our identity provider: 

• SCIM version: We support SCIM v2
• Single-sign-on URL: https://identity.codesignal.com/auth/sso?source=login
• Audience URI / SP Entity ID: https://app.codesignal.com
• SCIM connector base URL: https://identity.codesignal.com/api/scim/v2
• Supported provisioning actions: import new users and profile updates, push new users, push profile updates
• Authentication mode: HTTP headers
• Authorization: Bearer <Token>
  • Refer to Step 1 on how to retrieve your SCIM bearer token.
• Supported SCIM attributes: emails, name.givenName, and name.familyName, active, roles (optional)

Please note that Google Workspace does not support custom SCIM implementations.

Step 3: Check the email address format in your identity provider

CodeSignal uses the user’s email address for identification. That means that the email address attribute for a user should match between SAML SSO and SCIM user provisioning in your identity provider.

Ensure that your identity provider usernames are set to a value that indicates the primary email of the user. 

Step 4: Import and assign users

If available in your identity provider, we recommend importing and assigning existing CodeSignal users into your identity provider. This will fetch existing users from CodeSignal and allow you to automatically add or assign them to existing users in your identity provider.

Users added to CodeSignal will need to accept an invitation email before they can start using the platform. This process protects user privacy and ensures that users are not unintentionally added to a company. The invitation email gives users a chance to confirm their addition before applying company authentication restrictions to their accounts.

All new users added to CodeSignal through SCIM will be assigned the default role configured in Step 1.6. You can adjust their role from your CodeSignal Users and Teams dashboard once they accept the invitation.

Option 2: Using custom role assignments

This option is not a common way to use SCIM. It allows the Identity Provider to control roles through a User attribute, such as a department. This approach is risky because any manual changes made to roles directly on CodeSignal will automatically be overwritten by SCIM at the first opportunity, potentially causing inconveniences.

Step 1: Enable custom role assignments in SCIM

Step 2: Create the required roles in CodeSignal

To enable this configuration, your company will need to first set up the required roles in CodeSignal in preparation for Step 4.

To create a new role, you can find more information in this Support Article.

Step 3: Retrieve your Bearer Token from CodeSignal

1. Log in to your company's CodeSignal account as a Company Admin.
2. Click My Company Settings in the drop-down menu at the top right of your screen.
3. In the SSO tab, ensure that the Enable SSO toggle is on.
4. Navigate to the User Provisioning tab and toggle on Enable SCIM.
5. Click the Create button to generate a SCIM Token. Copy this token.
6. In the Default Role drop-down menu, choose the default role you'd like to assign to new users. While the role won’t be used in this SCIM configuration, it is a safety net in case you decide to switch to Option 1 or when the role is not passed from SCIM, even if role provisioning is enabled.

Step 4: Enable SCIM API integration in your identity provider

If your identity provider does not have a CodeSignal marketplace application, you will need the following information to enable the SCIM API integration in our identity provider: 

• SCIM version: We support SCIM v2
• Single-sign-on URL: https://identity.codesignal.com/auth/sso?source=login
• Audience URI / SP Entity ID: https://app.codesignal.com
• SCIM connector base URL: https://identity.codesignal.com/api/scim/v2
• Supported provisioning actions: import new users and profile updates, push new users, push profile updates
• Authentication mode: HTTP headers
• Authorization: Bearer <Token>
  • Refer to Step 1 on how to retrieve your SCIM bearer token.
• Supported SCIM attributes: emails, name.givenName, and name.familyName, active, roles (optional)

Please note that Google Workspace does not support custom SCIM implementations.

The “roles” parameter has to be an array with a single object containing role key in the “value” field.

Example:

Company XYZ wants to assign user John Doe (john.doe@xyz.com) the role of “Recruiter”. In CodeSignal, “Company Admin” has the role key TR4znQ4jEexfXF4ss.recruiter. Here is an example of what a POST SCIM V2 request with permission_level will look like: 

CodeSignal currently does not support the ability to define a user under multiple roles. A user can only be assigned to one role. 

Role values should be the ID of the role created on CodeSignal. Role keys are generated automatically. To find a role key, navigate to Users & Teams -> All Roles -> Click on a role. The part following roles/ is the role key:

Step 5: Check the email address format in your identity provider

CodeSignal uses the user’s email address for identification. That means that the email address attribute for a user should match between SAML SSO and SCIM user provisioning in your identity provider.

Ensure that your identity provider usernames are set to a value that indicates the primary email of the user. 

Step 6: Import and assign users

If available in your identity provider, we recommend importing and assigning existing CodeSignal users into your identity provider. This will fetch existing users from CodeSignal and allow you to automatically add or assign them to existing users in your identity provider.

Users added to CodeSignal will need to accept an invitation email before users can start using the platform. This process protects user privacy and ensures that users are not unintentionally added to a company. The invitation email gives them a chance to confirm their addition before applying company authentication restrictions to their account.

All new users added to CodeSignal through SCIM will be assigned the default role configured in Step 1.6. You can adjust their role from your CodeSignal Users and Teams dashboard once they accept the invitation.

Option 3: Using SCIM 2.0 for Group Management

Our SCIM integration now includes support for group management, allowing administrators to handle group-related activities via SCIM protocols. This addition enhances the capability to manage groups more dynamically and better aligns with SCIM standards.

Current Limitations

• No support for bulk actions.
• Does not return members of a group.
• Does not support SCIM v1.0.
• Does not disable team management within the CodeSignal UI even though it is controlled by SCIM.

Following the initial setup for SCIM integration covered in the previous sections, proceed with these steps for group management:

Step 1: Enabling Group Management

Reach out to your CodeSignal Customer Success Manager or CodeSignal Support (support@codesignal.com) to express your interest in enabling group management in SCIM. The CodeSignal integration team must deploy and enable this feature to load the required configuration data.

Step 2: Setting Up Group Management in Your Identity Provider

When setting up group management, it is important to configure your Identity Provider (IdP) to support group operations via SCIM. The IdP generally handles the complexities of forming and sending the required SCIM requests based on your configurations. Here’s how you can ensure your IdP is prepared for group management:

Configure Group Management Features

1. Interface Setup: Most IdPs provide a user-friendly interface to configure how groups are managed. Ensure you enable and set up group management functionalities within this interface according to your organizational needs.

2. Map Group Attributes: Align the group attributes in your IdP with those expected by CodeSignal’s SCIM implementation. This involves setting up mappings for group names, member lists, and other relevant details to ensure that the information is accurately synchronized between systems. Refer to the Guide to Mapping Group Attributes section below for further details about how to set this up.

3. Operational Settings:

• Create Groups: Confirm that your IdP is configured to create new groups when necessary, reflecting these changes via SCIM to CodeSignal. This operation is generally handled internally by the IdP when a new group is created through its interface.
• Update Groups: Ensure your IdP supports updates to groups, such as changes in group name or membership. Updates made in the IdP should automatically sync to CodeSignal through SCIM PATCH or PUT requests.
• Delete Groups: Check that deletions of groups in the IdP are propagated to CodeSignal, which typically involves the IdP sending a DELETE request to CodeSignal.

Step 3: Review and Test

1. Testing: After configuration, perform test operations from your IdP to ensure that create, update, and delete actions for groups are properly reflected in CodeSignal.
2. Documentation: Consult your IdP's documentation or support for specific guidance on setting up SCIM for group management. This can provide additional insights and steps specific to your IdP.

Guide to Mapping Group Attributes

When configuring your IdP to manage groups via SCIM, you'll need to map the IdP's group attributes to the corresponding attributes recognized by CodeSignal. These mappings are vital for ensuring that the data transferred via SCIM is interpreted correctly by both systems. Below are the key attributes typically involved in SCIM group management and how they should be mapped:

Group Name (DisplayName)

IdP Attribute: Often labeled as DisplayName in SCIM-compatible systems.

CodeSignal Mapping: This should map to the displayName attribute in CodeSignal’s SCIM implementation. It represents the name of the group as it will appear in CodeSignal.

Group Members (Members)

IdP Attribute: This is usually a multi-valued attribute where each value is a complex object describing the group members, often including properties like value (user ID) and $ref (a reference URL to the user’s SCIM resource).

CodeSignal Mapping: Map this to the members attribute in CodeSignal. Ensure that each member object includes the value attribute, which should correspond to the unique identifier of the user in CodeSignal.

External ID (ExternalId)

IdP Attribute: Typically externalId, is used to store a unique identifier for the group from an external system.

CodeSignal Mapping: This should map to the externalId in CodeSignal’s SCIM schema.

Examples:

POST to /Groups

Replace group with PUT to /Groups/:groupId

Update group name with PATCH to /Groups/:groupId

Microsoft Entra Group Mappings

Maintenance

Renewing SCIM Bearer Tokens

SCIM Bearer Tokens expire every 6 months. You can find the expiration date beneath the token in CodeSignal. All CodeSignal admins will receive an email notification 2 weeks, 1 week, and 1 day before expiration. Any company admin can renew the SCIM token. However, this task should be performed by someone in your IT team -  ideally, the person who set it up initially would be the best to refresh or renew the token. Your IT admin should only click on renew when they are ready to change. This is because CodeSignal might reject any requests that are coming from your identity provider when the most current token is not set up yet. 

When you are ready to change the token, you can click on renew under My Company Settings > User Provisioning, and configure your identity provider to use the new token immediately. 

Disabling user accounts

SCIM through CodeSignal can disable user accounts according to user accounts in your identity provider. 

If your identity provider does not have a CodeSignal marketplace application, you will need to map your identity provider’s user status attribute to SCIM’s standard attribute, active. This is a boolean field, so the expected values are true or false.

Appendices

Reference Links

CodeSignal’s documentation and knowledge base contains several articles that explore some of the topics in this integration guide with more depth or detail.

CodeSIgnal Knowledge Base Resources 

• Knowledge Base Home Page

Quick Start Guides

If you are also responsible for onboarding or training new users we have a set of Quick Start Guides that can be used to help new users get familiar with the platform as quickly as possible.