Group Mapping Settings API

Group Mapping Settings API let you programmatically configure Group Mapping behavior after receiving the group information from the IdP.

You can configure Group Mappings behavior in the following scenarios:

  • When a user has no groups assigned
  • When a user has several conflicting groups assigned

Prerequisites

Retrieve the Sysdig API Token from the Sysdig UI to use with the API.

Replace the API_TOKEN with your API token in the API calls given below.

Retrieve Existing Group Mappings

To retrieve all the Group Mappings for your Sysdig instance:

Issue a curl GET request against the Sysdig Monitor endpoint:

curl -XGET -H 'Authorization: Bearer <API_TOKEN>' https://<HOSTNAME>/api/groupmappings

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <HOSTNAME> with the Sysdig domain associated with your region.

The output will provide a list of Group Mappings in the response:

{
	"groupMappings": [
		{
			"id": 2136,
			"groupName": "GroupOne",
			"role": "ROLE_TEAM_STANDARD",
			"systemRole": "ROLE_USER",
			"teamMap": {
				"allTeams": false,
				"teamIds": [
					20008990
				]
			},
			"weight": 32767
		},
		{
			"id": 2137,
			"groupName": "GroupTwo",
			"role": "ROLE_TEAM_EDIT",
			"systemRole": "ROLE_USER",
			"teamMap": {
				"allTeams": false,
				"teamIds": [
					20008990
				]
			},
			"weight": 32767
		}
	]
}

Retrieve Settings for the Existing Group Mappings

To retrieve settings for the Group Mapping associated with your Sysdig instance, do the following:

Issue a curl GET request against the Sysdig Monitor endpoint:

curl -XGET -H 'Authorization: Bearer <API_TOKEN>' https://<HOSTNAME>/api/groupmappings/settings

Replace the following:

  • <API_TOKEN> with the token you retrieved.
  • <HOSTNAME> with the Sysdig domain associated with your region.

The output provides Group Mapping settings in the response.

{
	"noMappingStrategy": "UNAUTHORIZED",
	"differentRolesSameTeamStrategy": "UNAUTHORIZED"
}

If you have not already configured Group Mappings, the response will be “Not Found” with a status 404. This is normal, and will change after you configure the behavior for the first time. For the default behavior, see Group Mapping behavior.

Change Group Mapping Settings

To change the Group Mapping settings:

Issue a curl PUT request against the Sysdig endpoint:

curl -XPUT -H 'Authorization: Bearer <API_TOKEN>' -d <PAYLOAD> https://<HOSTNAME>/api/groupmappings/settings

Replace the following:

  • <API_TOKEN> with the token you retrieved.

  • <HOSTNAME> with the Sysdig domain associated with your region.

  • <PAYLOAD> contains the strategies for the configurable options. See Group Mapping Configuration for more information.

    • differentRolesSameTeamStrategy: Determines which behavior to use when several groups exist placing the user in the same team with a different role.

      • UNAUTHORIZED - Users will not be able to log in
      • FIRST_MATCH - If conflicts are found, the first group mapping that matches is processed, no further group mapping is processed.
      • WEIGHTED - If weight is defined, weight information is used to resolve the conflict and place the user in the team with the correct role. The resolution is global, this option does not process team level conflicts.
      • WEIGHTED_BY_TEAM - Similar to WEIGHTED, but conflicts are resolved on the team level, not globally.
    • noMappingStrategy: Determines which behavior to use when the user has no groups mapped.

      • UNAUTHORIZED - Users will not be able to login.
      • DEFAULT_TEAM_DEFAULT_ROLE - Users will be able to login and will be placed in the default team with the default role.

      Structure the payload as follows:

      '{
      	// Options: "UNAUTHORIZED", "FIRST_MATCH", "WEIGHTED", "WEIGHTED_BY_TEAM"
      	"differentRolesSameTeamStrategy": "UNAUTHORIZED",
      
      	// Options: "UNAUTHORIZED" "DEFAULT_TEAM_DEFAULT_ROLE"
      	"noMappingStrategy": "UNAUTHORIZED"
      }'
      

​ If successful, the output matches the configuration that was sent.

{
	"noMappingStrategy": "UNAUTHORIZED",
	"differentRolesSameTeamStrategy": "UNAUTHORIZED"
}

Change Specific Group Mapping by ID

To change specific Group Mapping based on the ID:

Issue a curl PUT request against the Sysdig endpoint:

 curl -XPUT -H 'Authorization: Bearer <API_TOKEN>' -d <PAYLOAD> https://<HOSTNAME>/api/groupmappings/<GROUP_MAPPING_ID>

Replace the following:

  • <API_TOKEN> with the token you retrieved.

  • <HOSTNAME> with the Sysdig domain associated with your region.

  • <GROUP_MAPPING_ID> with the ID of the Group Mapping you want to alter. See Retrieve Existing Group Mappings.

  • <PAYLOAD> contains Group Mapping that overwrites the existing Group Mapping for a given Group Mapping ID.

    weight can be between 1 and 32767. The lower the weight, the higher the mapping priority. For more information, see Group Mapping.

    Structure the payload as follows:

    '{
    	"id": <GROUP_MAPPING_ID>,
    	"groupName": "GroupOne",
    	"role": "ROLE_TEAM_STANDARD",
    	"systemRole": "ROLE_USER",
    	"teamMap": {
    		"allTeams": false,
    		"teamIds": [
    			20008990
    		]
    	},
    	"weight": 32767
    }'
    

​ If successful, the output matches the configuration that was sent.

{
	"id": 2136,
	"groupName": "GroupOne",
	"role": "ROLE_TEAM_STANDARD",
	"systemRole": "ROLE_USER",
	"teamMap": {
		"allTeams": false,
		"teamIds": [
			20008990
		]
	},
	"weight": 32767
}