--- title: 'Tutorial: Manage Users, Groups, and Access Controls Using the Web API' canonical: https://openvpn.net/as-docs/v3/tutorials/tutorial--user-group-access-controls-via-api/ product: Access Server Docs description: Manage users, groups, authentication methods, access controls, VPN addressing, and routing settings in OpenVPN Access Server using the Web API. Includes practical API examples for common administration tasks. --- # Tutorial: Manage Users, Groups, and Access Controls Using the Web API ## Overview This tutorial provides examples for managing users, groups, and related Access Server properties using the Web API. You can use these examples to: - Create and delete users and groups. - Manage group membership. - View users and groups. - Configure user and group permissions. - Manage authentication methods. - Configure VPN IP addressing. - Manage access control rules. - Configure split tunnel and DNS settings. - View and disconnect VPN clients. - Control client profile generation. > **Tip** > > This tutorial uses the `sacli apicall` command, but you can also use cURL or the Swagger UI. Refer to [Tutorial: Test the New Web API (OpenAPI) in Access Server 3.0](https://openvpn.net/as-docs/v3/tutorials/tutorial--test-the-new-web-api--openapi--in-access-server-3-0.md). ## Prerequisites - Access Server 3.1.0 or newer. - Root privileges on your Access Server's console. - (Optional) A remote machine for running API calls. > **Important** > > The API specification can change between Access Server versions. Verify the API specification for your version before using these commands. > > Refer to: [Tutorial: Test the New Web API (OpenAPI) in Access Server 3.0](https://openvpn.net/as-docs/v3/tutorials/tutorial--test-the-new-web-api--openapi--in-access-server-3-0.md). ## Before you begin All examples in this tutorial assume you're connected to the Access Server console with root privileges. ### Placeholder values Replace the following placeholders with values appropriate for your environment: | **Placeholder** | **Description** | | --- | --- | | `` | User account name | | `` | Group name | | `` | User or group receiving the configuration | | `` | Authentication method | | `` | Configuration profile name | ### Apply configuration changes Some configuration changes require a warm restart before they take effect. When instructed, run: ``` sacli --method POST --url 'api/server/restart?restartMode=warm' --value '' apicall ``` ## Create users and groups Use the following commands to create users and groups. ### Create a user ``` sacli --method POST --url 'api/users/create' --value '{"name": ""}' apicall ``` ### Create a group ``` sacli --method POST --url 'api/groups/create' --value '{"name": ""}' apicall ``` ### Apply the changes Perform a warm restart if required. ## Manage group membership Use the following commands to assign users to groups. ### Add a user to a group ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "group": ""}]' apicall ``` ### Remove a user from a group ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "group": null}]' apicall ``` ### Apply the changes Perform a warm restart if required. ## View users and groups ### List all users ``` sacli --method POST --url 'api/users/list' --value '' apicall ``` ### List a specific user ``` sacli --method POST --url 'api/users/list' --value '{"users":[""]}' apicall ``` ### List all groups ``` sacli --method POST --url 'api/groups/list' --value '' apicall ``` ### List a specific group ``` sacli --method POST --url 'api/groups/list' --value '{"groups":[""]}' apicall ``` ## Block or unblock users and groups ### Block a user or group ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "deny": "true"}]' apicall ``` ### Unblock a user or group ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "deny": "false"}]' apicall ``` ### Restore inherited behavior ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "deny": null}]' apicall ``` ### Apply the changes Perform a warm restart if required. ## Disconnect VPN users ### Disconnect a single user ``` sacli --method POST --url 'api/vpn/client/disconnect' --value '{"users": ["brandonqa"], "reason": "Brandon should not be working after hours", "client_reason": "Clients disconnected for administrative reasons"}' apicall ``` ### Disconnect all VPN connections for multiple users ``` sacli --method POST --url 'api/vpn/client/disconnect' --value '{"users": ["brandonqa", "laurenqa"], "reason": "Brandon and Lauren should not be working after hours", "client_reason": "Clients disconnected for administrative reasons"}' apicall ``` ## Delete users and groups ### Delete a user ``` sacli --method POST --url 'api/users/delete' --value '{"users": [""]}' apicall ``` ### Delete a group ``` sacli --method POST --url 'api/groups/delete' --value '{"groups": [""]}' apicall ``` ### Apply the changes Perform a warm restart if required. ## View connected VPN users > **Tip** > > This endpoint retrieves the OpenVPN server status, including connected clients and information about the OpenVPN daemon(s). ### List connected VPN users ``` sacli --method GET --url 'api/vpn/status' --value '' apicall ``` ## Manage administrator privileges Use the following commands to grant or revoke administrator privileges for users or groups. ### Grant administrator privileges ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "admin": "true"}]' apicall ``` ### Revoke administrator privileges ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "admin": "false"}]' apicall ``` ### Restore inherited behavior ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "admin": null}]' apicall ``` ### Apply the changes Perform a warm restart if required. ## Manage auto-login privileges Use the following commands to grant or revoke auto-login privileges. ### Enable auto-login ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "autologin": "true"}]' apicall ``` ### Disable auto-login ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "autologin": "false"}]' apicall ``` ### Restore inherited behavior ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "autologin": null}]' apicall ``` ### Apply the changes Perform a warm restart if required. ## Configure authentication methods Use the following commands to assign authentication methods to users or groups. ### Assign an authentication method ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "auth_method": ""}]' apicall ``` Supported values for ``: - `local` - `pam` - `radius` - `ldap` - `saml` ### Apply the changes Perform a warm restart if required. ## Configure VPN address pools > **Tip** > > The default `` value is `Default`. If you're using a different configuration profile, replace it with the appropriate value. ### Configure a global dynamic subnet When users who aren't assigned to a group connect to the VPN, Access Server assigns addresses dynamically from this subnet. ``` sacli --method POST --url 'api/config-items/' --value '{"vpn.daemon.0.client.network": "172.27.224.0", "vpn.daemon.0.client.netmask_bits": "20"}' apicall ``` The default is `172.27.224.0/20`. ### Configure a global group subnet When users belong to a group without a specific group subnet configured, Access Server assigns addresses dynamically from this subnet. ``` sacli --method POST --url 'api/config-items/' --value '{"vpn.server.group_pool.0": "172.27.240.0/20"}' apicall ``` The default is `172.27.240.0/20`. ### Configure a specific group subnet Assign a dedicated subnet to a group: ``` sacli --method POST --url 'api/userprop/set' --value '[{"name":"","subnets":[{"netip":"192.0.2.0","prefix_length":24}]}]' apicall ``` Assign a static IP address from that subnet to a user: ``` sacli --method POST --url 'api/userprop/set' --value '[{"name":"","static_ipv4":"192.0.2.55"}]' apicall ``` ### Configure a specific group subnet and dynamic range ``` sacli --method POST --url 'api/userprop/set' --value '[{"name":"","subnets":[{"netip":"192.0.2.0","prefix_length":24}],"dynamic_ranges":[{"first_ip":"192.0.2.10","last_ip":"192.0.2.20"}]}]' apicall ``` ### Configure a global static subnet ``` sacli --method POST --url 'api/config-items/' --value '{"vpn.server.static.0.network": "198.51.100.0", "vpn.server.static.0.netmask_bits": "24"}' apicall ``` Assign a static IP address from the subnet: ``` sacli --method POST --url 'api/userprop/set' --value '[{"name":"","static_ipv4":"198.51.100.55"}]' apicall ``` ### Apply the changes Perform a warm restart if required. ## Configure access control rules Use the following examples to grant access to resources using NAT or routing. ### Grant access to a single IP using NAT ``` sacli --method POST --url 'api/userprop/access/set' --value '{"items_append":[{"type":"access_to_ipv4","username":"","access_route":{"accept":true,"type":"nat","subnet":{"netip":"198.51.100.5","prefix_length":32,"ipv6":false}}}]}' apicall ``` ### Grant access to a single IP using routing ``` sacli --method POST --url 'api/userprop/access/set' --value '{"items_append":[{"type":"access_to_ipv4","username":"","access_route":{"accept":true,"type":"route","subnet":{"netip":"198.51.100.5","prefix_length":32,"ipv6":false}}}]}' apicall ``` ### Grant access to a subnet (range of IP addresses) using NAT ``` sacli --method POST --url 'api/userprop/access/set' --value '{"items_append":[{"type":"access_to_ipv4","username":"","access_route":{"accept":true,"type":"nat","subnet":{"netip":"198.51.100.0","prefix_length":24,"ipv6":false}}}]}' apicall ``` ### Grant access to a subnet (range of IP addresses) using routing ``` sacli --method POST --url 'api/userprop/access/set' --value '{"items_append":[{"type":"access_to_ipv4","username":"","access_route":{"accept":true,"type":"route","subnet":{"netip":"198.51.100.0","prefix_length":24,"ipv6":false}}}]}' apicall ``` ### Grant access to TCP port 443 on a specific IP using NAT ``` sacli --method POST --url 'api/userprop/access/set' --value '{"items_append":[{"type":"access_to_ipv4","username":"","access_route":{"accept":true,"type":"nat","subnet":{"netip":"198.51.100.5","prefix_length":32,"ipv6":false,"service":[{"protocol":"tcp","start_port":"443"}]}}}]}' apicall ``` ### Apply the changes Perform a warm restart if required. ### Grant multiple access control rules in a single request You can add multiple access control rules for the same user or group in a single API request by including multiple entries in the `items_append` array. This reduces the number of requests required when assigning several resources to the same user or group. The following grants user `brandonqa` access to two individual IP addresses using NAT: ``` sacli --method POST --url 'api/userprop/access/set' --value '{"items_append":[{"type":"access_to_ipv4","username":"brandonqa","access_route":{"accept":true,"type":"nat","subnet":{"netip":"198.51.100.15","prefix_length":32,"ipv6":false}}},{"type":"access_to_ipv4","username":"brandonqa","access_route":{"accept":true,"type":"nat","subnet":{"netip":"198.51.100.20","prefix_length":32,"ipv6":false}}}]}' apicall ``` **Result** The user `brandonqa` can access both `198.51.100.15` and `198.51.100.20` through the VPN using NAT-based access rules. ## Manage split tunnel and DNS settings > **Tip** > > Use these settings to configure split-tunnel behavior for specific users or groups when the full tunnel is enabled globally. ### Disable internet traffic redirection and DNS server assignment ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "reroute_gw": "disable"}]' apicall ``` ### Disable internet traffic redirection, but continue assigning DNS servers ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "reroute_gw": "dns_only"}]' apicall ``` ### Use the global internet access and DNS settings ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "reroute_gw": "global"}]' apicall ``` ### Restore inherited behavior ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "reroute_gw": null}]' apicall ``` ## Create bypass routes Use bypass routes to exclude specific networks from the VPN tunnel. ### Create a bypass route ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "bypass_subnets": [{"ipv6": false, "netip": "198.51.100.0", "prefix_length": 24}]}]' apicall ``` ### Apply the changes Perform a warm restart if required. ## Control profile generation By default, users can generate client profiles. ### Allow profile generation ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "allow_generate_profiles": "true"}]' apicall ``` ### Prevent profile generation ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "allow_generate_profiles": "false"}]' apicall ``` ### Restore inherited behavior ``` sacli --method POST --url 'api/userprop/set' --value '[{"name": "", "allow_generate_profiles": null}]' apicall ``` ## Related tutorials - [Tutorial: Test the New Web API (OpenAPI) in Access Server 3.0](https://openvpn.net/as-docs/v3/tutorials/tutorial--test-the-new-web-api--openapi--in-access-server-3-0.md) - [Tutorial: Create Connection Profiles Using the Web API (OpenAPI)](https://openvpn.net/as-docs/v3/tutorials/tutorial--create-connection-profiles-with-web-api.md) - [Tutorial: Create Token URLs Using the Web API](https://openvpn.net/as-docs/v3/tutorials/tutorial--token-urls-via-the-web-api.md) - [Tutorial: Create OpenVPN Connect Bundled Client Installers Using the Web API](https://openvpn.net/as-docs/v3/tutorials/tutorial--create-bundled-client-installers-via-api.md) --- Prev: [Tutorial: Manage User and Group Properties from the Command Line](https://openvpn.net/as-docs/v3/tutorials/tutorial--user-and-group-properties-cli.md) Next: [Tutorial: How to Clear All Global Access Control Rules](https://openvpn.net/as-docs/v3/tutorials/tutorial--clear-global-access-control-rules.md) Index: https://openvpn.net/as-docs/llms.txt