On-Premises Directory Sign-In (Active Directory / LDAP) ​

Let your team sign in to GraphnAI with their on-premises Active Directory accounts over LDAPS. No cloud identity provider is needed.

Requires role: Admin (add directory sign-in to a running deployment, grant access). The setup wizard needs no sign-in, because no sign-in method exists yet.

Related: Managing Sign-In Methods After Setup, Multi-Provider Platform Authentication & Setup, Entra ID Setup Guide, User Management & RBAC, Security Architecture

Overview ​

Directory sign-in checks a username and password against your on-premises Active Directory over LDAPS. Use it on its own in an AD-only deployment, or next to cloud single sign-on.

At each sign-in, GraphnAI:

  1. Signs in to the directory with a dedicated read-only service account.
  2. Finds the user by account name or user principal name.
  3. Signs in to the directory as that user, with the password they typed.
  4. Reads the user's security groups to decide their role.

Access granted to a group follows the group's security identifier (SID). Renaming or moving the group in AD keeps its access.

Directory sign-in works for one Active Directory domain at a time.

NOTE

Directory sign-in is separate from the Identity Bridge, which collects Active Directory into the graph. Sign-in uses its own service account and connects over LDAPS only. See Identity Bridge for collection.

Prerequisites ​

  • The GraphnAI server can reach a domain controller on port 636 (LDAPS). The connection test tells you if it can't.
  • At least one of the domain controllers you list is a Global Catalog server of the same domain, reachable on port 3269. Sign-in can't be turned on until the Global Catalog check passes.
  • A dedicated read-only service account for sign-in. Don't reuse the Identity Bridge collection account. The account only needs to search users and read the tokenGroups attribute, which authenticated users can read by default.
  • The domain controller's CA certificate (PEM), if an internal CA issued its LDAPS certificate. On the Identity Providers page, GraphnAI can fetch the certificate chain for you instead.

Set Up an AD-Only Deployment (First Run) ​

When no sign-in method exists, open the setup link the server printed at first start (see Quick Start). The link starts the setup wizard. After the license step, it shows Choose how your team signs in.

  1. Select Active Directory (LDAPS).
  2. Fill in the Connect your Active Directory form:
    • Display name: the name shown on the sign-in page, for example "Acme Active Directory".
    • Domain: the short name people type before their username, as in ACME\jsmith.
    • Email domains: each email domain your users sign in with, for example acme.com. Select Add after each one.
    • Directory hosts: one host per row, as host or host:port. The port defaults to 636. Select Add host for another. GraphnAI tries them in order.
    • Base DN: for example DC=acme,DC=local.
    • Service account and Service account password: the read-only account's DN and its password.
    • Certificate authority (PEM, optional): paste the domain controller's CA certificate. See Certificate Verification.
    • Setup administrator email: the email or user principal name of the AD account that becomes the first Admin.
    • Auto-create accounts on first sign-in: off by default. See Auto-Created Accounts.
  3. If an Identity Bridge domain already exists, a banner offers Copy settings. It copies the domain's name, hosts, base DN and service account. Enter the password yourself.
  4. Select Test connection. The checklist shows each stage: the host reached (with its TLS version), the service account signed in, the base DN found, and the Global Catalog. Fix any failed row and test again.
  5. Select Save and continue. The directory is saved turned off, and a 24-hour verification window opens for this browser only.
  6. Enter the setup administrator's AD username and password, then select Sign in and finish.

GraphnAI signs in to the directory as that account and checks that its email or user principal name matches the setup administrator email. The directory is then turned on, your account becomes an Admin, and the dashboard opens.

From then on, the sign-in page shows the Active Directory form, and the setup wizard is closed.

Add Directory Sign-In to a Cloud Deployment ​

An Admin can add directory sign-in to a deployment that already uses cloud single sign-on. The cloud provider isn't changed.

  1. Select Admin > Identity Providers in the sidebar.
  2. In On-premises directory sign-in, select Set up directory sign-in.
  3. Fill in the Directory sign-in dialog. The fields match the setup wizard, without a setup administrator email. List several hosts with commas between them.
  4. Select Test connection. If the directory's certificate isn't trusted, GraphnAI fetches its chain for you to review. See Trusting a Directory (LDAPS) Certificate.
  5. Select Save.
  6. Turn on Enable sign-in.

Turning it on runs the connection test again, Global Catalog included. A directory that fails the test stays off.

You can't change Domain after you save. To use another domain name, remove the directory and add it again.

The sign-in page then shows the single sign-on button, then "or", then the Active Directory form. Each method works on its own, so turning one off leaves the other working.

At least one sign-in method must stay active. When the directory is the only one, Enable sign-in is locked and Remove is disabled, with a line that says to add another method first.

Grant Access with AD Groups ​

Roles come from the AD security groups and accounts you add. People can't request access themselves.

  1. Select Admin > Users in the sidebar, then select Add user.
  2. If both cloud and directory sign-in are active, select the Active Directory tab.
  3. Choose a Type: User or Group.
  4. In Search the directory, type the start of a name. Group results list security groups only.
  5. Select the account or group, choose a Role, then select Add.

At each sign-in, GraphnAI reads the user's full security group membership live from AD, nested groups and the primary group included. Someone you remove from a group loses that access at their next sign-in, with no sync in between.

An account added on its own gets its own role, whatever its groups grant. Otherwise, when several of a user's groups have access, the highest role applies.

Auto-Created Accounts ​

Auto-create accounts on first sign-in is off by default. A directory sign-in succeeds for every enabled account in AD, service accounts and shared mailboxes included. With the setting on, any of them that signs in gets an account with the default role you choose, Viewer or Operator.

Grant access by group instead where you can. Change the setting in the Directory sign-in dialog. The change is recorded in the audit log.

Security Posture ​

Certificate Verification ​

Directory sign-in uses LDAPS only. There is no plain-text connection.

For production, give GraphnAI the domain controller's CA certificate. Paste it in Certificate authority (PEM, optional), or trust the fetched root on the Identity Providers page.

Allow unverified certificates (testing only) is off by default. With it on, GraphnAI doesn't check the directory's certificate. Every test report then carries a warning, and every sign-in logs one on the server. Add the CA certificate and turn it off before production.

Lockout and Enumeration Protection ​

Every failed sign-in shows the same message: "Invalid username or password." A wrong password, an unknown user, and a disabled, locked or throttled account all look the same, so the sign-in page can't be used to find account names.

GraphnAI stops failed attempts before they reach the domain controller. In any 15 minutes, it forwards at most:

  • 5 failed attempts per username.
  • 20 failed attempts per source address.

If your domain lockout threshold is very low, set its observation window with the per-username limit in mind. The count is kept in server memory, so a restart clears it.

A person with the right password but no access sees "Your account doesn't have access to GraphnAI. Ask your administrator to add you." That message appears only after the password is correct.

Expired Passwords ​

An expired password, or one AD requires to be changed, gets its own message: "Your password has expired. Contact your administrator to reset it, then sign in again." AD reports this only after it checks the password, so it discloses nothing to someone without it.

GraphnAI doesn't change AD passwords. Send affected users to your usual password reset process.

Passwords are never logged, stored, or included in metrics or audit records. The service account password is encrypted at rest.

Add Cloud Sign-In Later ​

An AD-only deployment can add cloud single sign-on at any time. Select Admin > Identity Providers, then Add provider. Directory sign-in keeps working while you add and activate the cloud provider. See Managing Sign-In Methods After Setup.

Troubleshooting ​

Message or symptomWhat to do
"Couldn't reach any directory host. Check the host names, and that port 636 is open from this server."Check the host names. Confirm the server can reach the domain controller on port 636.
"The directory's certificate isn't trusted. Add its CA certificate, then test again."Paste the CA certificate, or trust the fetched root on the Identity Providers page.
"The service account couldn't sign in. Check its DN and password."Correct the service account DN or password.
"The base DN wasn't found. Check it, for example DC=acme,DC=local."Correct the base DN.
"The service account signed in, but its own entry couldn't be read."Make sure the service account DN is exact and sits under the base DN.
"Couldn't reach a Global Catalog server for this directory."Open port 3269 from the server to a domain controller that hosts the Global Catalog.
The Global Catalog row says a host isn't a Global Catalog server, or belongs to a different domainList a domain controller of this directory's own domain that hosts the Global Catalog.
"Run a passing connection test, including the Global Catalog, before you turn this directory on."Select Test connection, fix any failed row, then turn sign-in on.
The sign-in page always says "Invalid username or password."The message never says why. Check the username, password and account status with your AD administrator.
"Your account doesn't have access to GraphnAI."Add the account, or one of its security groups, on Admin > Users.
A group grant has no effectOnly security groups grant access. An account added on its own keeps its own role, whatever its groups grant.
"That account isn't the setup administrator shown above."Sign in with the account whose email or user principal name matches the setup administrator email.
"The setup verification window expired."Select Restart directory setup and save the directory again.
Setup doesn't finish after you save the directoryComplete the verify step. Setup finishes only when the setup administrator signs in.