uControlAuthentication — LDAP, SAML & OpenID Connect
Authentication has moved into the Settings page. Find it at sidebar → Settings → Authentication tab. The old /admin/auth URL still works and redirects there. The standalone "Authentication" sidebar entry has been removed.
Authentication — LDAP, SAML & OpenID Connect
uControl Insight supports five authentication modes. The default is local. Enterprise environments can enable LDAP, SAML 2.0, or OpenID Connect.
All settings are configured from the admin UI at Settings → Authentication. No CLI or file editing required. Sensitive values are encrypted in the database.
Authentication Modes
| Mode | How It Works | Best For |
|---|---|---|
local | Username/password in database (BCrypt). Default. | Small teams, standalone |
ldap | Bind against Active Directory / LDAP. | AD without SSO |
hybrid | Try LDAP first, fall back to local. | Migration, admin fallback |
saml | SAML 2.0 SSO via ADFS/Okta/Azure AD. | Enterprise SSO with ADFS |
oidc | OpenID Connect SSO via Azure AD/ADFS/Keycloak. | Modern identity providers |
Users are auto-provisioned on first external login. Groups are mapped to uControl roles automatically.
Setup: ADFS SAML SSO
This is the most common enterprise setup. Follow these steps to configure ADFS as the identity provider.
Step 1: Create the Relying Party Trust on ADFS
Run the following PowerShell commands as Administrator on the ADFS server.
Create the SAML endpoint:
$ep = New-AdfsSamlEndpoint -Binding POST -Protocol SAMLAssertionConsumer -Uri "https://yourserver.example.com/uControlInsight/login/saml2/sso/adfs" -Index 0 -IsDefault $true Add-AdfsRelyingPartyTrust -Name "uControl Insight" -Identifier "ucontrol-insight" -SamlEndpoint @($ep) -AccessControlPolicyName "Permit everyone"
Replace yourserver.example.com/uControlInsight with your actual server URL and context path.
Step 2: Configure Claim Rules
The claim rules tell ADFS which attributes to include in the SAML assertion. The nameidentifier claim is required — without it, authentication will fail with “Assertion is missing a subject”.
| Claim | URI | AD Attribute | Purpose |
|---|---|---|---|
| UPN | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn | userPrincipalName | Username |
| Groups | http://schemas.xmlsoap.org/claims/Group | tokenGroups | Role mapping |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | User email | ||
| Display Name | http://schemas.microsoft.com/identity/claims/displayname | displayName | Full name |
| Name ID | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier | userPrincipalName | SAML Subject (required) |
Apply claim rules via PowerShell:
$rules = '@RuleTemplate = "LdapClaims" @RuleName = "Send LDAP Attributes" c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "http://schemas.xmlsoap.org/claims/Group", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "http://schemas.microsoft.com/identity/claims/displayname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"), query = ";userPrincipalName,tokenGroups,mail,displayName,userPrincipalName;{0}", param = c.Value);'
Set-AdfsRelyingPartyTrust -TargetName "uControl Insight" -IssuanceTransformRules $rules
Step 3: Configure uControl Insight
In the admin UI at Settings → Authentication:
- Select SAML 2.0 mode and click Save Mode
- Enable SAML 2.0 SSO
- Set Entity ID to
ucontrol-insight(must match the Identifier in the ADFS RP Trust) - Set ADFS Federation Metadata URL (e.g.,
https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml) - Set Username Attribute to
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn - Set Groups Attribute to
http://schemas.xmlsoap.org/claims/Group - Click Save SAML Config
- Configure group-to-role mappings (see below)
- Restart the application for changes to take effect
Group-to-Role Mappings
Map AD group names to uControl Insight roles. Matching is case-insensitive and supports full DN or CN-only.
| Role | Access Level |
|---|---|
ADMINISTRATOR | Full access to all features including platform settings, user management, and authentication |
DISCOVERY_ADMIN | Manage discovery targets, credentials, exclusions, and run scans |
READ_ONLY | View-only access to dashboards, assets, topology, and reports |
API_USER | API access only |
Users whose groups don’t match any mapping receive the Default Role (configurable, defaults to READ_ONLY).
SSO User Lookup
The SSO User Lookup feature helps administrators verify group names and configure role mappings without guessing.
How it works:
- When a user signs in via SSO (SAML or OIDC), uControl Insight captures their AD group memberships from the assertion
- Navigate to Settings → Authentication (with SAML or OIDC mode selected)
- Scroll to SSO User Lookup and search by username, name, or email
- Each user shows their exact group names as received from ADFS, plus their current mapped roles
- Click any group name to automatically add it to the Group-to-Role Mappings with the group pre-filled
- Select the desired role and click Save Mappings
Users must have signed in at least once via SSO for their groups to appear in the lookup. Groups are refreshed on every subsequent login.
Tip: Depending on how ADFS sends group claims, groups may appear with or without the domain prefix (e.g., UCTRL-Admins vs DOMAIN\UCTRL-Admins). Use the SSO User Lookup to verify the exact format before adding mappings.
Setup: LDAP
- Select Hybrid or LDAP mode
- Enable LDAP, fill in URL, Base DN, Manager DN/Password, search filters
- Save, then Test Connection
- Use LDAP User Lookup to verify groups
- Add group-to-role mappings, Save Mappings
- Save Mode, restart
Setup: OpenID Connect
- Select OpenID Connect mode, enable it
- Choose provider (Azure AD / ADFS / Keycloak)
- Download the appropriate IdP Setup Script — generates the client registration on your IdP
- Run the script, copy the Client ID/Secret/Issuer URI output
- Enter values in the OIDC form, Save
- Add group-to-role mappings, Save Mode, restart
Available setup scripts: ADFS (PowerShell), Azure AD (Azure CLI), Keycloak (kcadm.sh)
Login Page
SAML/OIDC modes show a Sign in with SSO button. A Sign in with local account link is always available for the built-in admin. Never delete the local administrator.
Self-Signed Certificates
ADFS with self-signed TLS certificates is handled automatically — metadata is fetched with TLS bypass on retry.
Troubleshooting
| Issue | Cause | Fix |
|---|---|---|
| “Invalid URI: The format of the URI could not be determined” | ADFS RP Trust has no SAML endpoint configured | Verify with Get-AdfsRelyingPartyTrust -Name "uControl Insight" | Select-Object -ExpandProperty SamlEndpoints. If empty, re-create using the PowerShell commands above. |
| “Assertion is missing a subject” | Claim rules don’t include nameidentifier | Re-apply the claim rules from Step 2, ensuring the nameidentifier type is included. |
| “Invalid username or password” after ADFS redirect | SAML assertion rejected (entity ID mismatch, metadata not loaded, or cert issue) | Check logs: grep "SAML_AUTH" catalina.out |
| SAML metadata fails at startup | ADFS unreachable when app starts | Ensure ADFS is accessible, then restart the application |
| Users get wrong roles (READ_ONLY) | Group names don’t match mappings | Use SSO User Lookup to verify exact group names from ADFS. Update mappings to match. |
| Mappings not working after DB update | Config cache is stale | Restart the application, or use the Authentication UI (which updates the cache automatically) |
| LDAP connection fails | Wrong URL, DN, or password | Verify settings and use Test Connection button |
| OIDC invalid_client | Wrong client secret | Re-enter Client Secret. Verify Client ID matches IdP. |
| Locked out after mode change | SSO misconfigured | Use “Sign in with local account” link on login page |