User Management API¶

User Management API

This API provides a way to manage FWD user accounts through REST endpoints, supporting full CRUD (Create, Read, Update, Delete) operations. It allows listing all users, retrieving individual user details, creating new users, cloning existing users, updating user properties, and deleting users. Additionally, it provides the ability to query group memberships for a given user.

The work on this feature was implemented in #10809.

Configuration¶

User Management API is a sub-module of Administration REST API. In order to enable user management support in FWD, the global REST API must be enabled. Please see the setup section. There are no additional requirements for this sub-module.

Add Permissions for the User Management API¶

In order to have access to the user management API, you need to add permissions. This is done via ACLs in the following manner:

<node class="container" name="security">
  <node class="container" name="acl">
    <node class="container" name="webservice">
      <node class="container" name="000100">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:GET:/admin/security/users"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000200">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:GET:/admin/security/users/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000300">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:POST:/admin/security/users"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000400">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:POST:/admin/security/users/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000500">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:PUT:/admin/security/users/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000600">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:DELETE:/admin/security/users/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
    </node>
  </node>
</node>

For the definition of admin-rest FWD user, please see the REST API Setup/Configuration.

By setting these, you will allow requests of the following types at the following paths:

Method	Path	Description	Body Required
`GET`	`/admin/security/users`	List all user accounts	No
`GET`	`/admin/security/users/<name>`	Get details of a specific user	No
`GET`	`/admin/security/users/<name>/groups`	List groups for a specific user	No
`POST`	`/admin/security/users`	Create a new user account	Yes (`name` required)
`POST`	`/admin/security/users/<name>/clone`	Clone an existing user account	Yes (`name` required)
`PUT`	`/admin/security/users/<name>`	Update an existing user account	Yes
`DELETE`	`/admin/security/users/<name>`	Delete a user account	No

User Object Reference¶

The following table describes all the fields of a user object as used in request and response payloads. All response payloads always include every field; fields that are not set for a given user appear as null.

Field	Type	Required	Unique	Description	Used In
`name`	String	Yes	Yes	The user account name (subject ID). Must be unique across all accounts (users and groups).	Request & Response
`email`	String	No	Yes (when set)	The user's email address. Must be unique across all users when provided. Can be `null`.	Request & Response
`oidcUuid`	String	No	Yes (when set)	OIDC UUID for SSO authentication. Must be unique across all users when provided. Can be `null`.	Request & Response
`enabled`	Boolean	No	No	Whether the account is enabled. Defaults to `false` if not specified.	Request & Response
`person`	String	No	No	The account owner's description/name. Can be `null`.	Request & Response
`alias`	String	No	No	Truststore alias of the associated certificate entry. Can be `null`.	Response only
`osUser`	String	No	No	Associated OS user ID. Can be `null`.	Request & Response
`password`	String	No	No	Plain text password (will be hashed server-side). Not required for SSO-authenticated users. When set, `protect` is automatically set to `true`.	Request only
`protect`	Boolean	No	No	Whether password protection is in effect. Automatically set to `true` when a password is provided. Must be `false` for SSO-only users that authenticate via OIDC.	Response only
`mode`	Integer	No	No	Authorization mode override for this account. Defaults to `0` (no override / inherit from group or server defaults).	Request & Response
`authPlugin`	String	No	No	Custom authentication plugin class name. Can be `null` to use the default.	Request & Response
`groups`	String[]	No	No	Array of group names the user belongs to. Each referenced group must already exist. Can be `null` or empty.	Request & Response
`passwordChanged`	Long	N/A	No	Timestamp (milliseconds since epoch) of when the password was last changed. Set automatically by the server when a password is assigned. `null` if no password has ever been set.	Response only

API Routes¶

The User Management API has the following capabilities:

Login: the login and logout operations are provided by the main module. For an example of how this is achieved, take a look at REST Admin Authentication.

The bash examples build on Administration REST API so use that as a basis, especially login, logout, api and handling of the session ID.

Show basic script usage Show basic script usage

#!/bin/bash
set -euo pipefail

require_command curl
require_command jq
require_command awk

base_url="${FWD_BASE_URL:-https://localhost:8443}" 
rest_user="${FWD_REST_USER:-restAdmin}" 
rest_token="${FWD_REST_TOKEN:-admin}" 

# Login
if ! session_id="$(login "$rest_user" "$rest_token")"; then
   echo "Login failed" >&2
   exit 1
fi

# Trap to logout so we don't need to explicitly logout after script failures
trap 'logout "$session_id" >/dev/null 2>&1 || true' EXIT
...

logout "$session_id"

Show login function Show login function

##############################################################################
# Login
##############################################################################

login()
{
   local rest_user="$1" 
   local rest_token="$2" 
   local headers
   local session_id

   headers="$(
      curl \
         --silent \
         --show-error \
         --fail \
         --location \
         --user "${rest_user}:${rest_token}" \
         --dump-header - \
         --output /dev/null \
         "${base_url}/admin/login" 
   )" 

   session_id="$(
      awk '
         BEGIN { IGNORECASE=1 }

         /^FwdSessionId:/ {
            gsub("\r", "", $2)
            print $2
         }
      ' <<< "$headers" 
   )" 

   if [[ -z "$session_id" ]]; then
      echo "ERROR: login failed, missing FwdSessionId" >&2
      return 1
   fi

   printf '%s\n' "$session_id" 
   return 0
}

Show logout function Show logout function

##############################################################################
# Logout
##############################################################################

logout()
{
   local session_id="$1" 

   if [[ -z "${session_id:-}" ]]; then
      echo "WARNING: no active session" >&2
      return 0
   fi

   curl \
      --silent \
      --show-error \
      --fail \
      --location \
      --request GET \
      --header "FwdSessionId: ${session_id}" \
      --output /dev/null \
      "${base_url}/admin/logout" 

   echo "Logged out successfully" 
   return 0
}

Show main API function Show main API function


##############################################################################
# Common REST API wrapper
##############################################################################

function api()
{
   local session_id="$1" 
   local method="$2" 
   local path="$3" 
   local body="${4:-}" 

   local response
   local http_code

   response="$(
      curl \
         --silent \
         --show-error \
         --location \
         --write-out $'\n%{http_code}' \
         --request "$method" \
         --header "FwdSessionId: ${session_id}" \
         --header "Content-Type: application/json" \
         ${body:+--data "$body"} \
         "${base_url}${path}" 
   )" 

   http_code="${response##*$'\n'}" 
   response="${response%$'\n'*}" 

   if [[ "$http_code" -lt 200 || "$http_code" -ge 300 ]]; then
      printf 'ERROR: %s %s failed with HTTP %s\n' \
         "$method" "$path" "$http_code" >&2

      if jq -e . >/dev/null 2>&1 <<< "$response"; then
         jq . <<< "$response" >&2
      else
         printf '%s\n' "$response" >&2
      fi

      return 1
   fi

   printf '%s\n' "$response" 
   return 0
}

List All Users¶

List all FWD user accounts by performing a GET request at /admin/security/users. The header must contain the FwdSessionId token. No body is required.

The response body will be a JSON object containing a users array. Each entry includes all user account fields. Fields that are not set for a given user appear as null.

Show example Show example

Request:

GET /admin/security/users HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

Response (HTTP 200):

{
  "users": [
    {
      "name": "admin",
      "email": null,
      "oidcUuid": null,
      "enabled": true,
      "person": "System Administrator",
      "alias": null,
      "osUser": null,
      "protect": true,
      "mode": 0,
      "authPlugin": null,
      "passwordChanged": 1739318400000,
      "groups": [
        "admins" 
      ]
    },
    {
      "name": "jdoe",
      "email": "jdoe@example.com",
      "oidcUuid": "550e8400-e29b-41d4-a716-446655440000",
      "enabled": true,
      "person": "John Doe",
      "alias": "shared",
      "osUser": "jdoe",
      "protect": true,
      "mode": 0,
      "authPlugin": null,
      "passwordChanged": 1739318400000,
      "groups": [
        "users",
        "everybody" 
      ]
    },
    {
      "name": "jsmith",
      "email": null,
      "oidcUuid": null,
      "enabled": true,
      "person": "Jane Smith",
      "alias": null,
      "osUser": null,
      "protect": false,
      "mode": 0,
      "authPlugin": null,
      "passwordChanged": null,
      "groups": [
        "users",
        "everybody" 
      ]
    }
  ]
}

Show BASH sample - List users Show BASH sample - List users

# List all users
if response="$(api "$session_id" GET "/admin/security/users")"; then
   jq . <<< "$response" 
else
   echo "List users failed" >&2
   exit 1
fi
# Extract some data
user_count="$(
   jq '.users | length' <<< "$response" 
)" 
echo "Found ${user_count} users"

Get User Details¶

Retrieve detailed information about a specific user by performing a GET request at /admin/security/users/<name>. The header must contain the FwdSessionId token. No body is required.

The response body will be a JSON object containing all user account properties. Fields that are not set appear as null.
If the user does not exist, a 404 Not Found response is returned with an error message.

Show example - user found Show example - user found

Request:

GET /admin/security/users/jdoe HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

Response (HTTP 200):

{
  "name": "jdoe",
  "email": "jdoe@example.com",
  "oidcUuid": "550e8400-e29b-41d4-a716-446655440000",
  "enabled": true,
  "person": "John Doe",
  "alias": "shared",
  "osUser": "jdoe",
  "protect": true,
  "mode": 0,
  "authPlugin": null,
  "passwordChanged": 1739318400000,
  "groups": [
    "users",
    "everybody" 
  ]
}

Show example - user not found Show example - user not found

Request:

GET /admin/security/users/nonexistent HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

Response (HTTP 404):

{
  "error": "User not found" 
}

Show BASH sample - Get user details Show BASH sample - Get user details

# Get one user
user="jdoe" 
if response="$(api "$session_id" GET "/admin/security/users/${user}")"; then
   jq . <<< "$response" 
else
   echo "List user=${user} failed" >&2
   jq . <<< "$response" 
   exit 1
fi

List Groups for a User¶

Retrieve the groups a specific user belongs to by performing a GET request at /admin/security/users/<name>/groups. The header must contain the FwdSessionId token. No body is required.

The response body will be a JSON object containing a groups array. Each entry has name and description properties.

Show example Show example

Request:

GET /admin/security/users/jdoe/groups HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

Response (HTTP 200):

{
  "groups": [
    {
      "name": "users",
      "description": "Regular Users" 
    },
    {
      "name": "everybody",
      "description": "All Users" 
    }
  ]
}

Show BASH sample - List user groups Show BASH sample - List user groups

# List user groups
user="jdoe" 
if response="$(api "$session_id" GET "/admin/security/users/${user}/groups")"; then
   jq . <<< "$response" 
else
   echo "List groups for user=${user} failed" >&2
   jq . <<< "$response" 
   exit 1
fi

Create a New User¶

Create a new FWD user account by performing a POST request at /admin/security/users. The header must contain the FwdSessionId token. The body must be a JSON object containing at least the name field.

On success, the response body will be a JSON containing {"success": true}.
On failure, the response returns HTTP 400 Bad Request.
The name field is required. All other fields are optional.

Show example - user creation Show example - user creation

Request:

POST /admin/security/users HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "name": "jdoe",
  "email": "jdoe@example.com",
  "oidcUuid": "550e8400-e29b-41d4-a716-446655440000",
  "enabled": true,
  "person": "John Doe",
  "password": "SecureP@ss123",
  "mode": 0,
  "authPlugin": "",
  "groups": ["users", "everybody"]
}

Response (HTTP 200):

{
 "success": true 
}

Show example - failure (missing name)Show example - failure (missing name)

Request:

POST /admin/security/users HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "email": "noname@example.com" 
}

Response: HTTP 400 Bad Request

Show BASH sample - Create a new user Show BASH sample - Create a new user


# Create a user
user="jdoe" 
email="jdoe@example.com" 
enabled=true
person="John Doe" 
password="SecureP@ss123" 
groups="users,everybody" 
json="$(
   jq -n \
      --arg user "$user" \
      --arg email "$email" \
      --arg person "$person" \
      --arg password "$password" \
      --arg groups "$groups" \
      --argjson enabled "$enabled" \
      '
      {
         name: $user,
         email: $email,
         enabled: $enabled,
         person: $person,
         password: $password,
         groups: (
            $groups
            | split(",")
            | map(gsub("^\\s+|\\s+$"; ""))
         )
      }
      '
)" 
if response="$(api "$session_id" POST "/admin/security/users" "$json")"; then
   jq . <<< "$response" 
else
   echo "Create user=${user} failed" >&2
   jq . <<< "$response" 
   exit 1
fi

Clone a User¶

Clone an existing user account by performing a POST request at /admin/security/users/<name>/clone. The header must contain the FwdSessionId token. The body must be a JSON object containing at least the name field for the new clone.

Because certain user fields must be unique (see the User Object Reference), the clone operation automatically sets the email and oidcUuid fields to null on the cloned user by default. You can provide new values for these fields in the request body to assign them to the clone instead.

<name> in the URL is the source user to clone from.
The body name field specifies the new user's name (required).
The optional email field sets the email for the cloned user. If omitted, it defaults to null (to avoid uniqueness violations with the source user).
The optional oidcUuid field sets the OIDC UUID for the cloned user. If omitted, it defaults to null (to avoid uniqueness violations with the source user).
The optional copyAcls boolean field controls whether ACLs are copied from the source user (defaults to false).
The optional password field sets a new password for the cloned user. If omitted, the cloned user inherits the source user's password settings.
On success, the response body will contain {"success": true}.

Show example - simple clone Show example - simple clone

Request:

POST /admin/security/users/jdoe/clone HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "name": "jdoe_copy" 
}

Note: The cloned user jdoe_copy will have email and oidcUuid set to null, even if the source user jdoe had them set.

Response (HTTP 200):

{
 "success": true 
}

Show example - clone with ACLs new password

Request:

POST /admin/security/users/jdoe/clone HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "name": "jdoe_backup",
  "email": "jdoe.backup@example.com",
  "copyAcls": true,
  "password": "NewSecureP@ss456" 
}

Response (HTTP 200):

{
 "success": true 
}

Show BASH sample - Clone a user Show BASH sample - Clone a user

# Clone a user
srcuser="jdoe" 
destuser="jdoe_copy" 
copyacls=true
password="NewSecureP@ss456" 
json="$(
   jq -n \
      --arg destuser "$destuser" \
      --argjson copyacls "$copyacls" \
      --arg password "$password" \
      '
      {
        "name": $destuser,
        "copyAcls": $copyacls,
        "password": $password
      }
      '
)" 
if response="$(api "$session_id" POST "/admin/security/users/${srcuser}/clone" "$json")"; then
   jq . <<< "$response" 
else
   echo "Clone user=${srcuser} to destuser=${destuser} failed" >&2
   jq . <<< "$response" 
   exit 1
fi

Update a User¶

Update an existing user account by performing a PUT request at /admin/security/users/<name>. The header must contain the FwdSessionId token. The body must be a JSON object with the user properties to update.

<name> in the URL identifies the user to update and takes priority over any name field in the body.
On success, the response body will contain {"success": true}.
On failure, the response returns HTTP 400 Bad Request.
Only the fields provided in the body will be applied; Allows you to change only specific fields, and also setting them to null in the JSON will delete the value for that user.

Show example - update email and person Show example - update email and person

Request:

PUT /admin/security/users/jdoe HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "email": "john.doe@newdomain.com",
  "person": "John M. Doe",
  "enabled": true
}

Response (HTTP 200):

{
 "success": true 
}

Show BASH sample - Updating email and person info

# Update only selected fields
user="jdoe" 
email="john.doe@newdomain.com" 
enabled=true
person="John Q. Doe" 
json="$(
   jq -n \
      --arg email "$email" \
      --argjson enabled "$enabled" \
      --arg person "$password" \
      '
      {
        "email": $email,
        "person": $person,
        "enabled": $enabled
      }
      '
)" 
if response="$(api "$session_id" PUT "/admin/security/users/${user}" "$json")"; then
   jq . <<< "$response" 
else
   echo "Update user=${srcuser} failed" >&2
   jq . <<< "$response" 
   exit 1
fi

Show example - change password Show example - change password

Request:

PUT /admin/security/users/jdoe HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "password": "NewSecureP@ss789" 
}

Response (HTTP 200):

{
 "success": true 
}

Show BASH sample - Change password Show BASH sample - Change password

# Update only selected fields
user="jdoe" 
password="NewSecureP@ss789" 
json="$(
   jq -n \
      --arg password "$password" \
      '
      {
        "password": $password
      }
      '
)" 
if response="$(api "$session_id" PUT "/admin/security/users/${user}" "$json")"; then
   jq . <<< "$response" 
else
   echo "Update user=${srcuser} failed" >&2
   jq . <<< "$response" 
   exit 1
fi

Show example - disable a user account Show example - disable a user account

Request:

PUT /admin/security/users/jdoe HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "enabled": false
}

Response (HTTP 200):

{
 "success": true 
}

Show BASH sample - Disable a user Show BASH sample - Disable a user

# Disable a user
user="jdoe" 
enabled=false
json="$(
   jq -n \
      --argjson enabled "$enabled" \
      '
      {
        "enabled": $enabled
      }
      '
)" 
if response="$(api "$session_id" PUT "/admin/security/users/${user}" "$json")"; then
   jq . <<< "$response" 
else
   echo "Disabling user=${srcuser} failed" >&2
   jq . <<< "$response" 
   exit 1
fi

Show example - update group memberships Show example - update group memberships

Request:

PUT /admin/security/users/jdoe HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "groups": ["admins", "users", "everybody"]
}

Response (HTTP 200):

{
 "success": true 
}

Show BASH sample - Update group membership

# Create a user
user="jdoe" 
newgroups="everybody" 
json="$(
   jq -n \
      --arg groups "$newgroups" \
      '
      {
         groups: (
            $groups
            | split(",")
            | map(gsub("^\\s+|\\s+$"; ""))
         )
      }
      '
)" 
if response="$(api "$session_id" PUT "/admin/security/users/${user}" "$json")"; then
   jq . <<< "$response" 
else
   echo "Update group membership for user=${user} to groups=${newgroups} failed" >&2
   jq . <<< "$response" 
   exit 1
fi

Delete a User¶

Delete an existing user account by performing a DELETE request at /admin/security/users/<name>. The header must contain the FwdSessionId token. No body is required.

<name> in the URL identifies the user to delete.
On success, the response body will contain {"success": true}.
On failure, the response returns HTTP 400 Bad Request.

Show example Show example

Request:

DELETE /admin/security/users/jdoe HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

Response (HTTP 200):

{
 "success": true 
}

Show BASH sample - Delete a user Show BASH sample - Delete a user

# Delete a user
user="jdoe" 
if response="$(api "$session_id" DELETE "/admin/security/users/${user}")"; then
   jq . <<< "$response" 
else
   echo "Deleting user=${user} failed" >&2
   jq . <<< "$response" 
   exit 1
fi

Error Handling¶

The API uses standard HTTP status codes to indicate the outcome of each request:

Status Code	Description
`200 OK`	The request was processed successfully.
`400 Bad Request`	The request was malformed, missing required fields, or the target path was invalid (e.g., nested paths for single-resource operations).
`401 Unauthorized`	The `FwdSessionId` header is missing or the session token is invalid/expired.
`404 Not Found`	The specified user was not found (only for `GET /admin/security/users/<name>`).

For mutating operations (POST, PUT, DELETE), a successful execution returns:

{
 "success": true 
}

A failed execution returns:

{
 "success": false 
}

If errors are collected during the operation, they are included in the response:

{
  "success": false,
  "errors": [
    "Error message 1",
    "Error message 2" 
  ]
}

Note:

<name> corresponds to the FWD user account name (subject ID).
All requests require the FwdSessionId header with a valid session token obtained via the login endpoint.
Use GET /admin/security/users to retrieve all available users before performing targeted operations.
When providing a password field in POST or PUT requests, the password is sent as plain text and hashed server-side.

Project

General

Profile

FWD

Wiki

User Management API¶

Configuration¶

Add Permissions for the User Management API¶

User Object Reference¶

API Routes¶

List All Users¶

Get User Details¶

List Groups for a User¶

Create a New User¶

Clone a User¶

Update a User¶

Delete a User¶

Error Handling¶