WebADM Framework APIs

APIs Overview

The Manager interface provides access to various WebADM management functions and operations exported by your registered applications. It allows external systems, such as web portals, to remotely trigger user management operations and actions from the network.

The LDAP management functions support LDAP operations such as object creation, update, removal management. The method names for internal management functions follow the format Manager_Method.
Operations exported by registered applications offer access to features available from the application actions in the Admin Portal. The method names for application-exported functions follow the format Application.Manager_Method.

The interface communication protocol is based on the JSON-RPC v2.0 specification. You can find the JSON-RPC specification at JSON-RPC 2.0 Specification.

You can visit the Manager Interface page in the WebADM Admin menu to see a full listing of the supported Manager functions and parameters. From there, you can navigate between applications to view the Manager functions supported by a specific registered application.

The Manager API requires authentication, and a WebADM administrator account must be provided to access the interface.

Authentication on the manager interface supports PKI, UID, and DN methods. This is configurable in /opt/webadm/conf/webadm.conf.
If you set admin_auth with multi-factor (PKI, OTP, or U2F), then you must use either manager_auth PKI or UID with a list of allowed client IPs in the manager_clients setting.

• With DN login mode, the administrator DN and password must be provided in the HTTP-Basic Authorization header.
• With UID login mode, the administrator user ID and password must be provided in the HTTP-Basic Authorization header.
• With PKI login mode, the administrator's user certificate must be used to establish the HTTPS connection to the interface, and the administrator password must be provided in the HTTP-Basic Authorization header.

manager_auth UID
manager_clients "locahost","192.168.4.253","192.168.3.205","127.0.0.1","192.168.4.191"

Any LDAP permission or OptionSet restriction configured in WebADM will be enforced within the Manager interface. Administrators have the same level of access in the Manager interface as they do in the Admin Portal.

A connection to the Manager automatically creates an Administrator session in WebADM for processing the requested methods if manager_session in webadm.conf is greater than 0.
The Manager responses return a session cookie called WEBADMMANAG in the response headers. You can pass the session cookie in subsequent Manager requests to avoid starting new sessions.
Manager sessions have a short expiration time and are automatically closed after 10 seconds of inactivity. You can force the closure of a session by passing the "Connection: close" header to the requests.

By default, all users or group members designated as super_admins in webadm.conf have access to the Manager Interface, provided that the IP from which the API calls originate is allowed.
You don't necessarily need to be part of the super_admins definition to consume the Manager APIs. Another option is to create an Administrator role from the WebADM Admin GUI > Admin tab, assign a user/group to that role, configure the Allowed Interface setting to Manager, and define the permissions allowed through that role.
If you do not want to provide LDAP permissions for actions done through the Manager APIs, you can configure in the ad

Once these requirements are met, you should be able to consume the WebADM APIs.

The Manager interface is accessible at the URL: https://<webadm_fqdn_or_ip_address>/manag/.

All Manager functions are listed and described through the WebADM Admin GUI > Admin tab > Remote Manager Interface.

Below are a few simple examples of using the WebADM Manager interface. The examples are written in PHP and use the cURL extension to send the JSON-RPC call over HTTP.

Resolve the DN of an Existing User

From the shell with curl:

curl -k \
 --user "cn=admin,o=root:password" \
 --header "Content-Type: application/json" \
 --data '{"method":"Get_User_DN", "params": {"username":"test_user", "domain": "Default"}, "id":0, "jsonrpc":"2.0"}' \
 https://webadm1.rcdevsdocs.com/manag/

With PHP:

<?php
$method = 'Get_User_DN';
$params = array(
	'username' => 'test_user',
	'domain' => 'Default',
);

$request = array(
	'jsonrpc' => "2.0",
	'method' => $method,
	'params' => $params,
	'id' => 0);
$json = json_encode($request);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webadm1.rcdevsdocs.com/manag/");
curl_setopt($ch, CURLOPT_USERPWD,"cn=admin,o=root:password");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("connection: close"));
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
$out = curl_exec($ch);
curl_close($ch);

print_r(json_decode($out));
?>

The manager will return a structure in the form:

stdClass Object
(
    [jsonrpc] => 2.0
    [result] => cn=test_user,o=Root
    [id] => 0
)

If you use PKI Authentication for the manager API, the following example applies with an administrator user certificate in PEM format:

<?php
$method = 'Get_User_DN';
$params = array(
	'username' => 'test_user',
	'domain' => 'Default',
);
# curl requires full path to certificate files
$caFile = getcwd() . '/ca.crt';
$keyFile = getcwd() . '/admin.key.pem';
$certFile = getcwd() . '/admin.crt.pem';
$certPass = "certpassword";

$request = array(
	'jsonrpc' => "2.0",
	'method' => $method,
	'params' => $params,
	'id' => 0);
$json = json_encode($request);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webadm1.rcdevsdocs.com/manag/");
curl_setopt($ch, CURLOPT_SSLKEY, $keyFile);
curl_setopt($ch, CURLOPT_CAINFO, $caFile);
curl_setopt($ch, CURLOPT_SSLCERT, $certFile);
curl_setopt($ch, CURLOPT_SSLCERTPASSWD, $certPass);
curl_setopt($ch, CURLOPT_USERPWD,"cn=admin,o=Root:password");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("connection: close"));
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
$out = curl_exec($ch);
curl_close($ch);

print_r(json_decode($out));
?>

Search Email for LDAP Users with the webadmAccount Extension

$method = 'Search_LDAP_Objects';
$params = array(
	'basedn' => 'o=root',
	'filter' => '(objectclass=webadmaccount)',
	'attrs' => array('mail')
);

Will return:

stdClass Object
(
    [jsonrpc] => 2.0
    [result] => stdClass Object
        (
            [cn=test1,o=Root] => stdClass Object
                (
                    [mail] => stdClass Object
                        (
                            [0] => test1@rcdevdocs.com
                        )
                )
	[cn=test2,o=Root] => stdClass Object
                (
                    [mail] => stdClass Object
                        (
                            [0] => test2@rcdevdocs.com
                        )
                )
        )
    [id] => 0
)

Set the User Mobile Number and Email Address

$method = 'Set_User_Attrs';
$params = array(
	'dn' => 'cn=test,o=root', 
	'attrs' => array('mobile' => array('12345678'), 'mail' => array('test@rcdevdocs.com')),
);

Will return:

stdClass Object 
(
    [jsonrpc] => 2.0
    [result] => 1
    [id] => 0
)

Get the User Mobile Number and Email Address

From the shell with curl:

curl -k --user "cn=admin,o=root:password"\
 --header "Content-Type: application/json"\
 --data '{"method":"Get_User_Attrs", "params": {"dn":"cn=test,o=root","attrs":{"0":"mobile","1":"mail"}},"id":0, "jsonrpc":"2.0"}'\
 https://webadm1.rcdevsdocs.com/manag/

Will return:

{"jsonrpc":"2.0","result":{"mail":{"0":"test@rcdevdocs.com"},"mobile":{"0":"12345678"}},"id":0}

With PHP:

$method = 'Get_User_Attrs';
$params = array(
	'dn' => 'cn=test,o=root', 
	'attrs' => array('mobile', 'mail'),
);

Will return:

stdClass Object
(
    [jsonrpc] => 2.0
    [result] => stdClass Object
        (
            [mobile] => Array
                (
                    [0] => 12345678
                )

            [mail] => Array
                (
                    [0] => test@rcdevdocs.com
                )

        )

    [id] => 0
)

Set User Settings (OpenOTP settings here)

$method = 'Set_User_Settings';
$params = array(
	'dn' => 'cn=test,o=root', 
	'settings' => array('OpenOTP.LoginMode' => 'LDAPOTP', 'OpenOTP.SecureMail' => false),
);

Will return:

stdClass Object 
(
    [jsonrpc] => 2.0
    [result] => 1
    [id] => 0
)

Register a HOTP Token with OpenOTP

$method = 'OpenOTP.HOTP_Register';
$params = array(
	'dn' => 'cn=test,o=root',
	'key' => base64_encode("12345678901234567890"),
	'counter' => 0

,
);

Will return:

stdClass Object 
(
    [jsonrpc] => 2.0
    [result] => 1
    [id] => 0
)

Validate an OTP Code with OpenOTP

$method = 'OpenOTP.OTP_Validate';
$params = array(
	'dn' => 'cn=test,o=root',
	'password' => '123456',
);

Will return:

stdClass Object 
(
    [jsonrpc] => 2.0
    [result] => 1
    [id] => 0
)

Get the OpenOTP User Information

$method = 'OpenOTP.UserInfo';
$params = array(
	'dn' => 'cn=test,o=root',
);

Will return:

stdClass Object 
(
    [jsonrpc] => 2.0
    [result] => stdClass Object
        (
            [UserID] => test
            [Domain] => Default
            [LDAPDN] => cn=test,o=Root
            [FullName] => Test User
            [Email] => test@rcdevsdocs.com
            [ChallengePolicy] => OTP
            [ChallengeMode] => self
            [LoginMode] => LDAPOTP
            [OTPLength] => 6
            [OTPSignature] => 
            [Tokens] => stdClass Object
                (
                    [Token1] => stdClass Object
                        (
                            [Type] => HOTP
                            [Status] => OK
                            [LastLogin] => 2022-01-01 00:00:00
                            [LastSuccess] => 2022-01-01 00:00:00
                            [LastFailure] => 
                            [FailureCount] => 0
                            [Options] => 
                        )
                )
        )
    [id] => 0
)

Signing a certificate signing request (CSR)

The manager API allows you to submit a CSR, which will be signed by the Rsignd service and the signed certificate is returned in the response.

You can generate the CSR using any tool, but in this example, we will use OpenSSL. The command below generates a private key and associated CSR for a user certificate named test-cert in the WebADM User Domain Default:

openssl req -new -newkey rsa:4096 -nodes -keyout user.key  -out user.csr  -subj '/CN=Default\\test-cert/UID=test-cert/DC=Default/description=USER/SN=test-cert'

To generate an Admin certificate, which can be used for WebADM and Manager API authentication or to login on the WebADM Administaror GUI, you can use the following command.

openssl req -new -newkey rsa:4096 -nodes -keyout admin.key -out admin.csr -subj '/CN=cn=test-cert,o=root/description=ADMIN/SN=test-cert'

The distinction between a User and an Admin certificate is typically defined by the description field and the subject. Refer to PKI section for more information.

When you have the CSR, you can have it signed by WebADM CA through the Manager API:

<?php
$method = 'Sign_certificate_Request';
$params = array(
	        'request' => file_get_contents("user.csr"),
        );

$request = array(
	'jsonrpc' => "2.0",
	'method' => $method,
	'params' => $params,
	'id' => 1);
$json = json_encode($request);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webadm1.rcdevsdocs.com/manag/");
curl_setopt($ch, CURLOPT_USERPWD,"Default\\admin:password");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("connection: close"));
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
$out = curl_exec($ch);
curl_close($ch);

print_r(json_decode($out));
?>

This will return the certificate in PEM format.
To use the certificate for authentication, it must be registered on a user, you can use the Set_User_attrs method for this:

$cert = file_get_contents("user.crt");
$method = 'Set_User_Attrs';
$params = array(
    'dn' => 'cn=test-cert,o=root',

    'attrs'=> array(
    'usercertificate'=> array(preg_replace ( '/(-----.*-----)|\s/','', $cert)),
  ),
    'values' => True
);

This should give you a good starting point for using the WebADM Manager interface for user management and application operations. Make sure to refer to the specific API documentation and examples for further details and advanced usage.