User Type REST Endpoint

Last modified 23 Apr 2024 08:14 +02:00
Table of Contents

User Type REST Endpoint

Here we are describing the User object type in relation to midPoints REST API. The User objects are a part of the REST API web resources.

Endpoint
users/

Operations And Examples

The User web resource is a part of the Create-Read-Update-Delete (CRUD) web resources present in midPoint. This is apparent in the operations which are available for this type of object.

In our examples we are authenticating with the credentials, name "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080.

For some help regarding the REST examples please see this link:

How to use MidPoint REST examples

Create User Object

Create a new User object in MidPoint with file data source
curl --user administrator:y0uR_P455woR*d \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/users \
-v \
--data-binary @./samples/rest/user-jack.json
Show data source example for "Create a new User object in MidPoint" | GitHub 
{
  "user": {
    "name": "jack",
    "fullName": "Jack Sparrow",
    "givenName": "Jack",
    "familyName": "Sparrow"
  }
}

The response is an HTTP 201 code in case of success without a response body. Also, the response contains a Location Header pointing to the location of the created user.

Example location header
 # Location: http://localhost:8080/midpoint/ws/rest/users/e4b0c81e-7fc7-462d-a92c-b3e0b10b8b49

Get User Object

Get operation for fetching a single specific object.

Get Object in JSON format with the Raw option set to true
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-X GET http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002?options=raw \
-v
Show JSON Example

The example is simplified, some properties were removed to keep the example output "short". This example does not contain all possible properties of this object type.

{
  "user" : {
    "oid" : "00000000-0000-0000-0000-000000000002",
    "name" : "administrator",
    "indestructible" : true,
    "assignment" : [ {
      "@id" : 1,
      "identifier" : "superuserRole",
      "targetRef" : {
        "oid" : "00000000-0000-0000-0000-000000000004",
        "relation" : "org:default",
        "type" : "c:RoleType"
      },
      "activation" : {
        "effectiveStatus" : "enabled"
      }
    }, {
      "@id" : 2,
      "identifier" : "archetype",
      "targetRef" : {
        "oid" : "00000000-0000-0000-0000-000000000300",
        "relation" : "org:default",
        "type" : "c:ArchetypeType"
      },
      "activation" : {
        "effectiveStatus" : "enabled"
      }
    } ],
    "iteration" : 0,
    "iterationToken" : "",
    "archetypeRef" : {
      "oid" : "00000000-0000-0000-0000-000000000300",
      "relation" : "org:default",
      "type" : "c:ArchetypeType"
    },
    "roleMembershipRef" : [ {
      "oid" : "00000000-0000-0000-0000-000000000300",
      "relation" : "org:default",
      "type" : "c:ArchetypeType"
    }, {
      "oid" : "00000000-0000-0000-0000-000000000004",
      "relation" : "org:default",
      "type" : "c:RoleType"
    } ],
    "credentials" : {
      "password" : {
        "value" : {
          "clearValue" : "5ecr3t"
      }
    },
    "fullName" : "midPoint Administrator",
    "givenName" : "midPoint",
    "familyName" : "Administrator"
  }
}
}

Search for User Objects

Search operation usable for fetching the full list of objects or a list based on filter.

Search for All Users With Name That Starts With 'a'
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/users/search \
-v \
--data-binary @./samples/rest/query-gen-name.json
Show data source example for "Search for name starting with 'a'" | GitHub 
{
  "query": {
    "filter": {
      "text": "name startsWith \"a\""
    }
  }
}

The response is an HTTP 200 code in case of success with a response body containing the queried items.

Example Output is a list of objects. 
{
  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
  "object" : {
    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#ObjectListType",
    "object" : [ {
      "@type" : "",
      "oid" : "",
      "version" : "",
      "name" : "",
      "metadata" : {},
      "operationExecution": {},
      "indestructible": ,
      "iteration" : ,
      "iterationToken" : "",
      "archetypeRef": {},
      "roleMembershipRef": {},
      "activation": {}
    }, {
      "@type" : "",
      "oid" : "",
      "version" : "",
      "name" : "",
      "metadata" : {},
      "operationExecution": {},
      "indestructible": ,
      "iteration" : ,
      "iterationToken" : "",
      "archetypeRef": {},
      "roleMembershipRef": {},
      "activation": {}
    } ]
  }
}

Modify User Objects

Modification of an attribute for specific user
curl --user administrator:y0uR_P455woR*d \
-H "Content-Type: application/json" \
-X PATCH http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002 \
-v \
--data-binary @./samples/rest/modify-attribute-gen.json -v
Show data source example for "Modify attribute value" | GitHub 
{
	"objectModification": {
		"itemDelta": {
			"modificationType": "add",
			"path": "description",
			"value": "Description parameter modified via REST"
		}
	}
}

The response is an HTTP 204 code in case of success without a response body.

Delete User Objects

Object deletion.

Delete a User type object
curl --user administrator:y0uR_P455woR*d \
-v \
-X DELETE http://localhost:8080/midpoint/ws/rest/users/e4b0c81e-7fc7-462d-a92c-b3e0b10b8b49

The response is an HTTP 204 code in case of success without a response body.

User Object Specific Operations

A set of operations specific for the User REST objects. i.e. password reset and others.

Execute Password Reset by Administrator for User

Please see note:

This example also needs a configuration change in the system global security policy. You have to enable the password reset feature in you configuration, please see this page.

 
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/users/e297a878-89da-43fa-b67a-d0316975388a/credential \
-v \
--data-binary @./samples/rest/user-pwd-reset.json
Show data source example for "Execute password reset by administrator for user" | GitHub 
{
  "executeCredentialResetRequest": {
    "resetMethod": "passwordReset",
    "userEntry": "5ecr3tP4s5w0rd"
  }
}

The response is an HTTP 200 code in case of success with a response body.

Show example output for "Execute password reset by administrator for user" 
{
  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
  "object" : {
    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#ExecuteCredentialResetResponseType",
    "message" : {
      "@type" : "c:SingleLocalizableMessageType",
      "key" : "execute.reset.credential.successful",
      "fallbackMessage" : "Reset password was successful"
    }
  }
}

Generate and Validate Operations for User Objects

Operations to generate or validate values, here we have an example of a simple password generate use-case.

Generate a Password for User
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/users/e297a878-89da-43fa-b67a-d0316975388a/generate \
-v \
--data-binary @./samples/rest/policy-items-password-generate.json
Show data source example for "Generate a password for user" | GitHub 
{
	"policyItemsDefinition": {
		"policyItemDefinition": {
			"target": {
				"path": "credentials/password/value"
			},
			"execute": "true"
		}
	}
}

The response is an HTTP 200 code in case of success with a response body.

Show example output for "Generate a password for user" 
{
  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
  "object" : {
    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#PolicyItemsDefinitionType",
    "policyItemDefinition" : [ {
      "target" : {
        "path" : "credentials/password/value"
      },
      "value" : {
        "@type" : "xsd:string",
        "@value" : "afruD"
      },
      "execute" : true
    } ]
  }
}

Common Use-case Examples

  1. Create User

  2. Get User Based on his unique identificator

  3. Get Users data with direct and indirect assignments

  4. User access request

  5. Access request review

UserType JSON Example

Example output of information regarding a specific object. Some data vas omitted to simplify the example.

Show JSON Example 
{
  "user" : {
    "oid" : "00000000-0000-0000-0000-000000000002",
    "name" : "administrator",
    "indestructible" : true,
    "assignment" : [ {
      "@id" : 1,
      "identifier" : "superuserRole",
      "targetRef" : {
        "oid" : "00000000-0000-0000-0000-000000000004",
        "relation" : "org:default",
        "type" : "c:RoleType"
      },
      "activation" : {
        "effectiveStatus" : "enabled"
      }
    }, {
      "@id" : 2,
      "identifier" : "archetype",
      "targetRef" : {
        "oid" : "00000000-0000-0000-0000-000000000300",
        "relation" : "org:default",
        "type" : "c:ArchetypeType"
      },
      "activation" : {
        "effectiveStatus" : "enabled"
      }
    } ],
    "iteration" : 0,
    "iterationToken" : "",
    "archetypeRef" : {
      "oid" : "00000000-0000-0000-0000-000000000300",
      "relation" : "org:default",
      "type" : "c:ArchetypeType"
    },
    "roleMembershipRef" : [ {
      "oid" : "00000000-0000-0000-0000-000000000300",
      "relation" : "org:default",
      "type" : "c:ArchetypeType"
    }, {
      "oid" : "00000000-0000-0000-0000-000000000004",
      "relation" : "org:default",
      "type" : "c:RoleType"
    } ],
    "credentials" : {
      "password" : {
        "value" : {
          "clearValue" : "5ecr3t"
      }
    },
    "fullName" : "midPoint Administrator",
    "givenName" : "midPoint",
    "familyName" : "Administrator"
  }
}
}

See Also

Was this page helpful?
YES NO
Thanks for your feedback