Use this guidance to automatically provision SecurityScorecard users in your organization with the System for Cross-domain Identity Management (SCIM) standard.
This is especially helpful if you have many people in your organization who need to use SecurityScorecard.
Configure SCIM for your SecurityScorecard account
After you complete these steps, you will not have to create or delete separate SecurityScorecard accounts for single-sign on (SSO) users in your organization. SecurityScorecard accounts will automatically be provisioned for these users.
Connect SecurityScorecard to your SCIM application
Note: Make sure that the user (or bot) account who owns the API token used in this step has permissions to create and update users and teams in the SecurityScorecard platform.
- Create an API token in SecurityScorecard.
- In your SCIM management application enter the following information:
-
For Base URL, enter the following endpoint:
https://platform-api.securityscorecard.io/scim/v2/. - Enter the API token you created in SecurityScorecard.
Configure SCIM roles
- In your identity provider (IdP) application, such as Okta Identity or Microsoft Azure AD, create an attribute and name it sscRoles.
-
Select one of the following role values.
Note: Roles not present in the table below are not currently supported, please reach out to your Account Team should you be interested in supporting additional roles.
The selected role will be assigned to your provisioned users:
Name Value Customer Admin CUSTOMER_ADMIN User VRM Read Only USER Guest GUEST - Set the data type to Array[string] if applicable.
- Set the external namespace to urn:ietf:params:scim:schemas:core:2.0:User.
Note: Every provisioned user is automatically assigned the role you select in the configuration, but you can manually change any user's role. Learn how to manage users and roles.
Creating Teams and assigning Role-Based Access Controls (RBAC)
When a groups is sent as part of the schema, a SecurityScorecard team will be automatically created and the user will automatically be assigned to that team.
1. To create new RBAC permissions for the team, go to ‘My Settings → People Management → Roles’ or select the following link: https://platform.securityscorecard.io/#/my-settings/user-management/roles
2. Select ‘Create New Role’, include Role name and desired permissions and save.
3. Navigate to the teams section at ‘My Settings → People Management → Teams' or by selecting the following link: https://platform.securityscorecard.io/#/my-settings/user-management/teams
4. Select the ellipsis (3 dots) next to the team name and select ‘Edit’.
5. Under the ‘Assign Permission access’ section, search for the created role name under the ‘Search for Permissions to add’ search bar and select the role name.
For further information on permissions and RBAC, please refer to the following articles:
- Manage users and permissions in SecurityScorecard
- Introducing Role Based Access Controls (RBAC) for Questionnaire
Deprovisioning Users
To deprovision a user in SecurityScorecard using the SCIM standard, you can use the PATCH operation on the /Users/{user_id} endpoint. Set the "active" attribute to false in the request body to deactivate the user account. Below is an example of the PATCH request:
Endpoint: PATCH https://platform-api.securityscorecard.io/scim/v2/Users/{user_id}
Request Body:
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "replace",
"value": { "active": false }
}]
}
Upon deprovisioning, the user will no longer be able to log in to the SecurityScorecard platform. However, the user's information will still be listed in the People Management section within the Settings.
SCIM Endpoints Examples
Users
Get All Users:
GET https://platform-api.securityscorecard.io/scim/v2/Users?startIndex=1&count=25
Get One User:
GET https://platform-api.securityscorecard.io/scim/v2/Users/{user_id}
Create User:
POST https://platform-api.securityscorecard.io/scim/v2/Users
Request Body:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "<Username>",
"name":
{
"givenName": "<GivenName>",
"middleName": "<MiddleName>",
"familyName": "<FaimlyName>"
},
"emails":
[{
"primary": true,
"value": "<Email>",
"type": "work"
}],
"displayName": "<DisplayName>",
"active": true
}
Update (Replace) User:
Endpoint: PUT https://platform-api.securityscorecard.io/scim/v2/Users/{user_id}
Request Body:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "<UserID>",
"userName": "username@example.com",
"name":
{
"givenName": "<GivenName>",
"familyName": "<FamilyName>"
},
"active": "true",
"emails":
[{
"primary": true,
"type": "work",
"value": "username@example.com"
}],
}
Update (Patch) User:
PATCH https://platform-api.securityscorecard.io/scim/v2/Users/{user_id}
Request Body:
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":
[{
"op": "replace",
"value": { "active":false }
}]
}
Groups
Get All Groups:
GET https://platform-api.securityscorecard.io/scim/v2/Groups?startIndex=1&count=250
Get One Group:
GET https://platform-api.securityscorecard.io/scim/v2/Groups/{group_id}
Create Group:
Endpoint: POST https://platform-api.securityscorecard.io/scim/v2/Groups
Request Body:
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Test Group",
"members": [
{
"value": "{user_id}",
"display": "email@email.com"
}
]
}
Update (Replace) Group:
PUT https://platform-api.securityscorecard.io/scim/v2/Groups/{group_id}
Request Body:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "<GroupID>",
"displayName": "<DisplayName>",
"members":
[{
"value": "<UserID>",
"$ref": "<UserSCIMLocation>",
"display": "First Last"
}]
}
Update (Patch) Group:
PATCH https://platform-api.securityscorecard.io/scim/v2/Groups/{group_id}
Request Body:
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":
[{
"op": "replace",
"value": { "displayName":"Test" }
}]
}