Security Management

5 min

The Security Management API addresses authentication tasks. These tasks apply to both local users and LDAP users.

Update Password for a User

This API changes the password for a single user.

Example:

https://<Ivanti EPMM>/api/v1/sm/authentication/users/jdoe

For security reasons, include the old and new passwords in the HTTP request body rather than as query parameters. For example:

PUT /api/v1/sm/authentication/users/jdoe HTTP/1.1

Host: <Ivanti EPMM>

Content-Length: 44

Accept: application/json

Authorization: Basic <token>

Content-Type: application/x-www-form-urlencoded

oldpassword=abcd1234&newpassword=wxy!13579

URI: https:///api/v1/sm/authentication/users/	Updates password for input username.
Http Method:	PUT
Format:	xml, json
Request:
username	Required. Unique login user name.
oldpassword	Current password of the user. Note: For security reasons, include this parameter in HTTP request body. Required only if the Ivanti EPMM setting to save the user password is set to Yes. You can set this value in the Admin Portal, using Settings \| Preferences. When oldpassword is required, make sure that the value you provide in the request is correct. If it is not included or is not correct, the response contains a failure message. Note: When you create a local user using the API to Register a Device, Ivanti EPMM sets the user’s password to the user ID (called username in this request).
newpassword	Required. New password of the user. The password must be between 8 and 20 characters. Note: For security reasons, include this parameter in HTTP request body.

Response Status Code:
‘404 – No Data Found’	There is no data.
‘200 – OK’	Data is present and the response is returned.
Response:
<securityManagementWebServiceResponse>
<userName>jdoe</userName>
<messages>
<message>
Password changed successfully for user: jdoe	Status Message. Success shown if the method execution is successful. A descriptive error message is shown if the method execution failed.
</ message >
</messages>
</securityManagementWebServiceResponse>

Find a User

This API finds a single user by username or email address. User details will be returned only if the search finds an exact match of the username or email address.

Example:

https://<Ivanti EPMM>/api/v1/sm/users/jdoe

URI: https:///api/v1/sm/users/	Finds the user specified for input username or email address
Http Method:	GET
Format:	xml, json
Request:

Response Status Code:
‘404 – No Data Found’	There is no data.
‘200 – OK’	Data is present and the response is returned.
Response:
<securityManagementWebServiceResponse> <userName>miadmin</userName> <messages/> <user id="9001"> <uuid>f89d8cbf-59d7-47e6-97c2-4681ed8f954a</uuid> <principal>miadmin</principal> <createdAt>1374085200000</createdAt> <displayName>miadmin</displayName> <email>[email protected]</email> <enabled>true</enabled> <firstName>miadmin</firstName> <forcePasswordChange>false</forcePasswordChange> <googleAppsEncryptionAlgVersion>0</googleAppsEncryptionAlgVersion> <lastAdminPortalLoginTime>1374178220915</lastAdminPortalLoginTime> <lastName></lastName> <opaque>true</opaque> <roles>ROLE_MPW_LOCK</roles> <roles>ROLE_USER_MANAGEMENT_RW</roles> <roles>ROLE_MAI_RW</roles> <roles>ROLE_APPS_AND_FILES_RW</roles> <roles>ROLE_SENTRY_FOR_IPAD</roles> <roles>ROLE_ADMIN_LOCATE</roles> <roles>ROLE_LOG_R</roles> <roles>ROLE_TROUBLESHOOTING_RW</roles> <roles>ROLE_EVENT_CENTER_RW</roles> <roles>ROLE_ADMIN_WIPE</roles> <roles>ROLE_SELECTIVE_WIPE</roles> <roles>ROLE_MPW_REG</roles> <roles>ROLE_SECURITY_AND_POLICIES_RW</roles> <roles>ROLE_MPW_LOCATE</roles> <roles>ROLE_API</roles> <roles>ROLE_SMARTPHONES_AND_DEVICES_RW</roles> <roles>ROLE_MPW_WIPE</roles> <roles>ROLE_USER_PORTAL_RW</roles> <roles>ROLE_CONNECTOR</roles> <roles>ROLE_SETTINGS_RW</roles> <userSource>76</userSource> </user> </securityManagementWebServiceResponse>

Search LDAP Users

This API finds users by username. The search string cannot be less than 2 characters. If the search results are more than the search limit (can be configured in mifs.properties) an error is returned. Default search limit is 100.

Example:

https://<Ivanti EPMM>/api/v1/sm/users/search/ldap/?userid=jdoe

URI: https:///api/v1/sm/users/search/ldap/	Finds the users for the specified username search string.
Http Method:	GET
Format:	xml, json
Request:
userid	Required. Username search string. Minimum 2 characters.
Response Status Code:
‘404 – No Data Found’	There is no data.
‘200 – OK’	Data is present and the response is returned.
‘400- Bad Request’	1. If the input search string is less than 2 characters. 2. If the search results are more than the limit.
Response:
<securityManagementWebServiceResponse> <userName>testuser000</userName> <messages/> <users> <user> <principal>testuser0001</principal> <displayName>testuser0001</displayName> <email>[email protected]</email> <enabled>false</enabled> <firstName>Test</firstName> <forcePasswordChange>false</forcePasswordChange> <lastName>User0001</lastName> <opaque>true</opaque> <userSource>68</userSource> </user> <user> <principal>testuser0003</principal> <displayName>testuser0003</displayName> <email>[email protected]</email> <enabled>false</enabled> <firstName>Test</firstName> <forcePasswordChange>false</forcePasswordChange> <lastName>User0003</lastName> <opaque>true</opaque> <userSource>68</userSource> </user> </users> </securityManagementWebServiceResponse>

Authenticate a User

This API authenticates a single user by username.

Example:

https://<Ivanti EPMM>/api/v1/sm/authentication

For security reasons, include the password in the HTTP request body rather than as a query parameter. For example:

POST /api/v1/sm/authentication HTTP/1.1

Host: <Ivanti EPMM>

Content-Length: 31

Accept: application/json

Authorization: Basic <token>

username=jdoe&password=abcd1234

URI: https:///api/v1/sm/users/	Finds the user specified for input username.
Http Method:	POST
Format:	xml, json
Request:
username	String Required Note: For security reasons, include this parameter in HTTP request body.
Password	String Required The password must be between 8 and 20 characters. Note: For security reasons, include this parameter in HTTP request body.
Response Status Code:
‘401 – Unauthorized’	If the username/password is invalid.
‘200 – OK’	If username and password are valid then User details are returned in the response.
Response:
<securityManagementWebServiceResponse> <userName>miadmin</userName> <messages/> <user id="9001"> <uuid>f89d8cbf-59d7-47e6-97c2-4681ed8f954a</uuid> <principal>miadmin</principal> <createdAt>1374085200000</createdAt> <displayName>miadmin</displayName> <email>[email protected]</email> <enabled>true</enabled> <firstName>miadmin</firstName> <forcePasswordChange>false</forcePasswordChange> <googleAppsEncryptionAlgVersion>0</googleAppsEncryptionAlgVersion> <lastAdminPortalLoginTime>1374178220915</lastAdminPortalLoginTime> <lastName></lastName> <opaque>true</opaque> <roles>ROLE_MPW_LOCK</roles> <roles>ROLE_USER_MANAGEMENT_RW</roles> <roles>ROLE_MAI_RW</roles> <roles>ROLE_APPS_AND_FILES_RW</roles> <roles>ROLE_SENTRY_FOR_IPAD</roles> <roles>ROLE_ADMIN_LOCATE</roles> <roles>ROLE_LOG_R</roles> <roles>ROLE_TROUBLESHOOTING_RW</roles> <roles>ROLE_EVENT_CENTER_RW</roles> <roles>ROLE_ADMIN_WIPE</roles> <roles>ROLE_SELECTIVE_WIPE</roles> <roles>ROLE_MPW_REG</roles> <roles>ROLE_SECURITY_AND_POLICIES_RW</roles> <roles>ROLE_MPW_LOCATE</roles> <roles>ROLE_API</roles> <roles>ROLE_SMARTPHONES_AND_DEVICES_RW</roles> <roles>ROLE_MPW_WIPE</roles> <roles>ROLE_USER_PORTAL_RW</roles> <roles>ROLE_CONNECTOR</roles> <roles>ROLE_SETTINGS_RW</roles> <userSource>76</userSource> </user> </securityManagementWebServiceResponse>