Use this guide to work with SecureAuth IdP's Identity Management APIs to leverage end-user profiles from the LDAP server, add and update profiles, and modify attributes in profiles. These tools enable administrator management of end-users (and limited end-user self-management via KBA) programmatically from the website, without the need to build connections directly to the data store.
API Identity Management tools can be used along with Authentication API features configured on the SecureAuth IdP realm, so that end-users can be securely directed through unique logins and interfaces without leaving the application.
1. Have access to the application code
2. Have an on-premises Active Directory with which SecureAuth IdP can integrate
3. Create a New Realm or access an existing realm in which the Identity Management APIs are enabled
The API can be included in any realm with any Post Authentication event as long as the appropriate directory is integrated and the appropriate settings are configured
4. Configure the Data tab in the SecureAuth IdP Web Admin
An Active Directory integration is required for SecureAuth IdP to pull user profile information during the login process
Note, however, the GET /user and update /user functions can work with non-AD integrations.
1. SecureAuth IdP Web Admin Steps
2. Configure Authorization Header & Response Header
3. Endpoints
- /users
- Configure Group Association Endpoints (/users or /groups)
1. Check Enable API for this realm in the API Key section
2. Click Generate Credentials to create a new Application ID and Application Key
The Application ID and Application Key are unique per realm
3. Click Select & Copy to copy the contents from the fields
These values are required in the Header configuration steps below
4. Check at least one Identity Management tool to include in the API
User management - add / update / retrieve users and their properties: Use this tool to add new user profiles, and to retrieve and update existing user profiles
Updating a user profile includes setting and / or clearing property values in the user profile
Administrator initiated password reset: Use this tool to let an administrator send the end-user a new password requested via an application
Use case scenario: The end-user requests a new password because the current one has been forgotten
User self-service password change: Use this tool to let the end-user input both the current password and a new password
Used in conjunction with the Administrator initiated password reset option, the end-user enters the password sent by the administrator (the current password), and then enters a new password
User & group association (LDAP): Use this tool to enable associations between existing users and groups within the LDAP data store
Click Save once the configurations have been completed and before leaving the API page to avoid losing change
Error rendering macro 'excerpt-include'
No link could be created for 'Admin API Guide (version 9.1+)'.
Information about /users Endpoints and Group Association Endpoints are documented in the sections below
The following endpoints are prepended with the URL, https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1
The /users GET endpoint retrieves a list of end-user profile properties – SecureAuth IdP accesses and retrieves the user's profile via the username in the endpoint URL
As a GET endpoint, there is no body, so no JSON parameters are required in the message body
| GET Endpoint | Example |
|---|---|
/users/{userId } | https://secureauth.company.com/secureauth2/api/v1/users/jbeam |
The /users PUT / POST endpoints add, update, or delete end-user profile properties – SecureAuth IdP updates the user's profile using the username in the endpoint URL
| PUT / POST Endpoint | Example |
|---|---|
/users/{userId} | https://secureauth.company.com/secureauth2/api/v1/users/jbeam |
The /users POST user endpoint creates the new end-user profile – no username is specified in the endpoint URL
| POST Endpoint | Example |
|---|---|
/users/ | https://secureauth.company.com/secureauth2/api/v1/users/ |
The /users POST resetpwd endpoint performs an administrative password reset for the end-user – SecureAuth IdP accesses the end-user's profile, resets the user's password and provides a new one using the username in the endpoint URL
| POST Endpoint | Example |
|---|---|
/users/{userId}/resetpwd | https://secureauth.company.com/secureauth2/api/v1/users/jbeam/resetpwd |
The /users POST changepwd endpoint performs a password reset for the end-user – SecureAuth IdP accesses the end-user's profile and lets the end-user change that password, using the username in the endpoint URL
| POST Endpoint | Example |
|---|---|
/users/{userId}/changepwd | https://secureauth.company.com/secureauth2/api/v1/users/jbeam/changepwd |
Admins can use POST messages to associate users with groups, and vice-versa
Types of associations to the /users or /groups endpoint include the following:
- Single user to single group
- Single user to multiple groups
- Single group to single user
- Single group to multiple users
This operation associates a single user in the data store with a single group in the data store
No message body is required since all parameters for this request are present in the call URL
| POST Endpoint | Example |
|---|---|
/users/{userId}/groups/{groupID to associate} | https://secureauth.company.com/secureauth2/api/v1/users/jbeam/groups/admins |
Result: userID "jbeam" is associated with the groupID "admins"
This operation associates a list of multiple users with a specified group
For multiple users, supply the list of users in the POST message body, not the URL
If any of the userIDs fail to POST, a failure response is generated which lists each userID that failed – userIDs not listed in the failure response successfully POSTed
| POST Endpoint | Example |
|---|---|
/users/{userId}/groups/{groupId}/users | https://secureauth.company.com/secureauth2/api/v1/groups/Sharepoint%20Visitors/users |
Result: group "Sharepoint Visitors" is associated with the list of users specified in the message body
This operation associates a group in the data store with a single user in the data store
This operation is functionally equivalent to the Single User to Single Group operation above
No message body is required since all parameters for this request are present in the call URL
| POST Endpoint | Example |
|---|---|
/groups/{groupID}/users/{userID to associate} | https://secureauth.company.com/secureauth2/api/v1/groups/admins/users/jbeam |
Result: groupID "admins" is associated with userID "jbeam"
This operation associates a single user with multiple groups at the same time
For multiple groups, supply the list of groups in the POST message body, not the URL
If any of the groupIDs fail to POST, a failure response is generated which lists each groupID that failed – groupIDs not listed in the failure response successfully POSTed
| POST Endpoint | Example |
|---|---|
/users/{userId}/groups | https://secureauth.company.com/secureauth2/api/v1/users/jbeam/groups |
Result: user "jbeam" is associated with a list of groups specified in the message body
If a server error is encountered, the following response is returned:
{
"status": "server_error",
"message": "<Exception message describing the issue.>",
}
HTTP Status 500