ARES Directory help

Getting started

1. Sign in as an administrator. On first start ARES creates the account Administrator. Its password is the one set in ARES_ADMIN_PASSWORD, or a random one printed once in the server log.
2. Open the admin console at /admin/. Only members of Domain Admins can open it.
3. Build your structure. Create organizational units (OUs) such as Staff, Service Accounts and Groups.
4. Create users and groups, and add users to groups.
5. Create a service account for each application that will read the directory over LDAP.
6. Connect applications over LDAP, or register them under Applications (SSO) for OpenID Connect.

Signing in

The sign-in page accepts any of these forms for the same account:

After one sign-in, every application connected through OpenID Connect or reverse-proxy SSO signs you in without asking again, until the session expires or you sign out.

If an administrator required a password change, ARES asks for the current and a new password before letting you continue.

Signing out from the portal or from an application ends the single sign-on session for all applications.

My account portal

Every user has a personal page at /account:

• My apps lists the applications you are allowed to use. Click a tile to open the app.
• Profile shows your logon names, email, phone, distinguished name and groups.
• Change password requires your current password. The new one must meet the password policy.

Administrators also see an Admin console button.

Directory concepts

ARES stores objects in a tree, exactly like Active Directory.

Distinguished name (DN)

The full path of an object, read from the object up to the root. CN=Jane Doe,OU=Staff,DC=cybercontrol,DC=tech means "Jane Doe, inside the Staff OU, inside the domain".

Base DN (naming context)

The root of the tree, derived from the domain name: DC=cybercontrol,DC=tech. Applications start their searches here.

Organizational unit (OU)

A folder for organizing objects, such as by department or location. OUs can contain other OUs.

Container

A built-in folder such as CN=Users or CN=Computers. Containers behave like OUs but are created by the system.

User

A person or service account that can sign in. Key names: sAMAccountName (logon name) and userPrincipalName (UPN, email-style).

Group

A set of users, computers or other groups. Groups grant access to applications. Membership can be nested: a member of a member counts.

memberOf

The list of groups an object belongs to directly. ARES computes it automatically from each group's member list.

objectGUID and objectSid

Permanent identifiers that never change, even when an object is renamed or moved. Applications should use them as stable keys.

Built-in objects

Objects marked System are critical and cannot be deleted or moved.

Admin console tour

The search box at the top searches names, logon names, emails and descriptions. Press Enter to run it.

Clicking an object opens its properties panel. The buttons at the top perform actions; the tabs show details. Press Esc to close it.

Managing users

Create a user

1. In Directory, open the OU where the user belongs, then choose + New ▸ User. Or use Users ▸ + New user, which creates in CN=Users.
2. Enter first and last name. The full name and logon name fill in automatically; edit them if needed.
3. Leave the UPN empty to use logon@cybercontrol.tech.
4. Type a password, or tick Generate a random password. A generated password is shown once.
5. Choose the options: must change password at next logon, password never expires, account is enabled.
6. Optionally add the user to groups, then click Create user.

A user created without a password starts disabled, as in Active Directory.

User properties

• General: name, contact details, job title, department, company, manager. Click Save changes after editing.
• Account: logon names, POSIX attributes for Linux (UID, GID, home directory, shell), account options, last logon, password last set, SID and GUID, and effective groups including nested ones.
• Member of: direct group memberships, with add and remove.
• Attribute editor: every raw attribute. See Attribute editor.

Common actions

Managing groups

1. Choose + New ▸ Group in an OU, or Groups ▸ + New group.
2. Enter the name. The pre-Windows 2000 name defaults to it.
3. Choose the scope and type:
   • Security groups grant access. Use them for application assignment.
   • Distribution groups are for mailing lists.
   • Global, Domain local and Universal scopes match Active Directory. In a single domain, Global is the usual choice.

Open a group to see its tabs: General (description, email, scope and type, manager), Members, Member of and Attribute editor. Click Add members to add users, computers or other groups.

Nesting: if group Engineering is a member of All Staff, every engineer is effectively in All Staff. Application assignment, the OIDC groups claim and the LDAP in-chain rule all honor nesting. A group cannot contain itself.

OUs and containers

• Create: open the parent, then + New ▸ Organizational unit.
• Open properties: click Container properties in the list toolbar. You can create objects inside, rename, move or delete from there.
• Delete: an OU that still contains objects can only be deleted with Also delete everything inside (tree delete). This cannot be undone.
• Move: moving an OU moves everything inside it, and all group memberships are updated.

Use + New ▸ Computer for machine accounts, and Other object (raw) to create any object class by typing its attributes.

Attribute editor

The last tab of every object lists all its attributes, like the Attribute Editor in Active Directory.

• Click Edit to change values, one value per line. Leave it empty to remove the attribute.
• Click + Add attribute to set any attribute, including custom ones your applications need.
• Attributes marked read-only are maintained by the server, such as objectGUID, whenCreated and memberOf. The naming attribute changes only through Rename.
• Password hashes are never shown.

SSO applications

Register each OpenID Connect application under Applications (SSO) ▸ + Register application.

After registering, the client secret is shown once. Copy it into the application. If it is lost, open the app and click New secret; the old secret stops working immediately.

Unassigned users who try to sign in see an "access denied" page naming the application.

Connecting applications via LDAP

Most self-hosted applications have an "LDAP" or "Active Directory" login option. Use these settings:

Applications configured for OpenLDAP also work: use (&(objectClass=inetOrgPerson)(uid=%s)) and groups of class groupOfNames.

Service accounts: create a user such as svc-gitlab in an OU like Service Accounts, with a long generated password and password never expires. Any signed-in account can read the directory, so service accounts need no extra rights. Never use the Administrator account in applications.

Test your filter first under Tools ▸ LDAP search tester.

Connecting applications via OpenID Connect

Choose "OpenID Connect", "OAuth2 / generic" or "Microsoft Entra-compatible" in the application, and enter:

Tokens are valid for one hour by default and are refreshed automatically. Disabling a user stops refreshes at once.

Reverse-proxy SSO (forward-auth)

For applications with no login integration, put them behind nginx, Traefik or Caddy and let the proxy ask ARES whether the visitor is signed in:

• The proxy calls https://ldap.cybercontrol.tech/auth/verify, optionally with ?group=Group%20Name to require a group.
• ARES answers 200 with headers Remote-User, Remote-Email, Remote-Name, Remote-Groups and Remote-UPN; 401 when not signed in; 403 when not in the group.
• Traefik and Caddy are redirected to the sign-in page automatically. For nginx, send 401 responses to https://ldap.cybercontrol.tech/login?next=<original URL>.
• The protected apps must be on subdomains of the configured cookie domain (ARES_COOKIE_DOMAIN) so the SSO cookie reaches them.

Tools: search, import, export

• LDAP search tester: enter a base DN, scope and filter, and see exactly which objects an application would find. Click a result to open it.
• Export (LDIF): downloads the whole directory without password hashes. Backup with password hashes includes them; store that file securely.
• Import (LDIF): paste or upload LDIF. Entries that already exist are skipped, and parents must appear before children. Password hashes from OpenLDAP ({SSHA}, {SSHA256}, {SSHA512}, {SHA}, {BCRYPT}, {CRYPT} bcrypt) keep working, so migrated users keep their passwords.

Audit log

Every sign-in, failed LDAP bind, password change, application authorization and directory change is recorded with time, actor, target, details and source IP address. Green entries succeeded and red entries failed. Use the filter box to find an actor, action or object. Records are kept for 90 days by default.

Security and policies

Always connect over LDAPS or StartTLS, or HTTPS for the web, so passwords are encrypted in transit.

Error codes

LDAP sign-in failures include an Active Directory-style code in the message (... data 52e ...):

Other LDAP result codes: 32 no such object (wrong base DN), 50 insufficient access (not a Domain Admin), 53 unwilling to perform (empty password or protected object), 66 the OU is not empty, 68 the name is already in use.

Troubleshooting

The application finds no users

Check the base DN and filter in the LDAP search tester. Make sure the bind account is enabled and its password correct.

A user cannot sign in to an SSO app

Check that the user is enabled and not locked, and is in one of the app's allowed groups. The audit log shows the exact reason.

"redirect_uri is not registered"

Copy the callback URL from the application's error into the app's Redirect URIs exactly, including scheme, port and trailing slash.

Certificate errors over LDAPS

The server may be using a self-signed certificate. Install a trusted certificate, or import the server certificate into the application.

Group membership changes are not visible in an app

OIDC apps see new groups at the next sign-in or token refresh. LDAP apps see them immediately.

Operations

• Backups: stop the service and copy the data directory, or keep regular LDIF backups.
• Forgotten administrator password: on the server, stop the service and run ares reset-admin -dataDir <data directory>, then start it again.
• Health check: GET /healthz returns ok.
• Version: shown below and in the console's About dialog; ares version on the server.