Group Mapping Settings API

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 -X GET -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 -X GET -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"
}

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.
    • NO_MAPPINGS_ERROR_REDIRECT - Users will not be able to login and will be redirected to a URL specified in noMappingsErrorRedirectURL. Make sure the URL is set and valid before using this option.

  • noMappingsErrorRedirectURL - URL to send the users to if noMappingStrategy is configured as NO_MAPPINGS_ERROR_REDIRECT. Please note that no validation of the redirect URL is performed.

    Structure the payload as follows:

    '{
    	// Options: "UNAUTHORIZED", "FIRST_MATCH", "WEIGHTED", "WEIGHTED_BY_TEAM"
    	"differentRolesSameTeamStrategy": "UNAUTHORIZED",
    
    	// Options: "UNAUTHORIZED", "DEFAULT_TEAM_DEFAULT_ROLE", "NO_MAPPINGS_ERROR_REDIRECT"
    	"noMappingStrategy": "UNAUTHORIZED",
    
    	// Options: Redirect URL (optional)
    	"noMappingsErrorRedirectURL": ""
    }'
    

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

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

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
}