Authentication Problems

Overview

Authentication problems in NetStacks can occur at multiple layers: logging into the NetStacks web UI or Terminal application, authenticating to the Controller API, unlocking the credential vault, or authenticating to managed network devices. Each layer uses different mechanisms and has distinct failure modes.

Authentication Failure Categories

• LDAP Binding Failures -- The Controller cannot connect to or authenticate against the LDAP/Active Directory server during user login.
• OIDC Token Issues -- Single sign-on via OpenID Connect fails due to misconfigured providers, expired tokens, or callback URL mismatches.
• JWT Expiry / Rejection -- API requests fail because the JSON Web Token has expired, is malformed, or was signed with the wrong key.
• Credential Vault Access -- Users cannot retrieve stored credentials due to vault lock, permission issues, or encryption key problems.
• SSH Key Rejection -- The target network device rejects the SSH key presented during device authentication.

How It Works

NetStacks authentication involves a multi-stage flow from user login through to device access. Understanding each stage helps you pinpoint where failures occur.

Authentication Flow

1. User Login -- The user authenticates to NetStacks via local credentials, LDAP bind, or OIDC redirect. On success, the Controller issues a JWT access token and a refresh token.
2. JWT Session -- All subsequent API requests include the JWT in the Authorization header. The Controller validates the token signature, expiry, and permissions on every request.
3. Token Refresh -- When the access token expires, the client automatically uses the refresh token to obtain a new access token without re-prompting for credentials.
4. Credential Vault Unlock -- When a device connection is initiated, NetStacks retrieves the appropriate credential from the encrypted vault. Credentials are isolated by owner -- users can only access their own credentials or those explicitly shared with them.
5. Device Authentication -- The retrieved credential (password, SSH key, or certificate) is used to authenticate to the target device over SSH or Telnet.

Step-by-Step Guide

Use the appropriate diagnostic checklist based on which authentication method is failing.

Local Authentication

1. Verify the username is typed correctly (case-sensitive).
2. Reset the password through the admin panel if forgotten.
3. Check if the account has been disabled by an administrator.
4. Verify the Controller service is running and healthy.

LDAP / Active Directory

1. Verify the LDAP server is reachable from the Controller host.
2. Check the Bind DN and Bind Password in admin settings.
3. Confirm the User Search Base DN includes the target user's OU.
4. Verify the User Filter pattern matches the login attribute (e.g., sAMAccountName vs uid).
5. Test with ldapsearch from the Controller host to isolate LDAP vs NetStacks issues.
6. If using LDAPS (port 636), verify the TLS certificate is trusted.

OIDC / SSO

1. Verify the Redirect URI in the OIDC provider matches the NetStacks callback URL exactly.
2. Confirm the Client ID and Client Secret are correct.
3. Check that required scopes (openid, profile, email) are configured.
4. Verify the OIDC provider's discovery endpoint is accessible from the Controller.
5. Check system clock synchronization -- JWT validation is time-sensitive.

SSH Key Authentication (to devices)

1. Verify the correct credential is assigned to the device in NetStacks.
2. Confirm the public key is installed on the target device.
3. Check key file permissions (private key must be 600 or more restrictive).
4. Verify the key type is supported by the device (some older devices reject Ed25519).
5. If using a passphrase-protected key, verify the passphrase is stored correctly in the vault.

Code Examples

LDAP Connection Test

# Test LDAP bind from the Controller host
ldapsearch -x -H ldap://ldap.example.com:389 \
  -D "cn=netstack-svc,ou=ServiceAccounts,dc=example,dc=com" \
  -W \
  -b "ou=Users,dc=example,dc=com" \
  "(sAMAccountName=jdoe)" dn

# Test LDAPS (TLS) connection
ldapsearch -x -H ldaps://ldap.example.com:636 \
  -D "cn=netstack-svc,ou=ServiceAccounts,dc=example,dc=com" \
  -W \
  -b "ou=Users,dc=example,dc=com" \
  "(uid=jdoe)" dn

JWT Token Inspection

# Decode a JWT token to inspect its claims (without verification)
# Split the token by '.' and base64-decode the payload (second segment)
echo "eyJhbGciOiJIUzI1NiIs..." | cut -d. -f2 | base64 -d 2>/dev/null | jq .

# Example decoded payload:
{
  "sub": "user-uuid-here",
  "username": "jdoe",
  "role": "admin",
  "iat": 1709856000,
  "exp": 1709859600
}

# Check if token is expired:
# Compare "exp" (expiry) timestamp to current time
date -d @1709859600  # Shows when the token expires

API Authentication Test

# Test API authentication with curl
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer <your-jwt-token>" \
  https://controller.example.com/api/v1/users/me

# 200 = authenticated successfully
# 401 = token invalid or expired
# 403 = authenticated but insufficient permissions

SSH Key Permission Check

# Verify SSH key file permissions
ls -la ~/.ssh/
# Expected:
# drwx------  .ssh/           (700)
# -rw-------  id_ed25519      (600)
# -rw-r--r--  id_ed25519.pub  (644)
# -rw-r--r--  authorized_keys (644)

# Fix permissions if incorrect
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Test SSH key auth directly
ssh -i ~/.ssh/id_ed25519 -o PreferredAuthentications=publickey admin@10.0.1.1

Q&A

Q: Why does LDAP authentication fail?

A: LDAP authentication failures are usually caused by one of: incorrect Bind DN or password in the NetStacks LDAP settings, the User Search Base DN not including the user's organizational unit, the user filter not matching the correct attribute (e.g., using uid when Active Directory uses sAMAccountName), or network connectivity issues between the Controller and the LDAP server. Test with ldapsearch from the Controller host to isolate whether the issue is LDAP configuration or NetStacks configuration.

Q: How do I debug OIDC/SSO login issues?

A: Start by verifying the Redirect URI configured in your OIDC provider matches the NetStacks callback URL exactly (including protocol, host, port, and path). Check the browser developer console for error details during the redirect flow. Common issues include mismatched Client ID/Secret, missing required scopes, and the OIDC discovery endpoint being unreachable from the Controller. If using a self-signed certificate on the OIDC provider, ensure the Controller trusts it.

Q: Why is my JWT token rejected?

A: JWT tokens can be rejected for several reasons: the token has expired (check the exp claim), the system clocks are out of sync between the client and Controller (JWT validation is time-sensitive), the token was issued by a different Controller instance, or the signing key has been rotated. If tokens expire too quickly, an administrator can adjust the token lifetime in Settings. The client should automatically refresh tokens before they expire.

Q: How do I fix "Permission denied (publickey)"?

A: This error means the target device rejected the SSH key. Verify that: the correct public key is installed in the device's authorized keys configuration, the private key file has correct permissions (600), the key type is supported by the device (older Cisco IOS may not support Ed25519 -- use RSA 2048+ instead), and the credential assigned to the device in NetStacks matches the key installed on the device. Also check if the device has a maximum number of authorized keys configured.

Q: Why can't I access the credential vault?

A: Credential vault access issues can stem from: the vault being locked (requires re-authentication), insufficient permissions (you can only access your own credentials or credentials explicitly shared with you via folder grants), or the encryption key being unavailable. If the vault was recently migrated, the encryption key derivation may need to be re-initialized. Contact your administrator if you believe you should have access to a shared credential.

Q: How do I reset my credentials if locked out?

A: If you are locked out of NetStacks, an administrator can reset your password through the admin panel under User Management. If LDAP/OIDC is the only authentication method and the provider is down, an administrator can temporarily enable local authentication as a fallback. For device credentials stored in the vault, those are preserved -- only the NetStacks login needs to be recovered.

Q: Why does my session expire faster than expected?

A: Session expiry is controlled by the JWT token lifetime configured in admin settings. If the refresh token is also expired, you will be prompted to log in again. Common causes of unexpected expiry include: system clock drift between the client and Controller, the administrator reducing token lifetimes, or the browser blocking the automatic token refresh request. Check that your browser allows cookies and JavaScript for the Controller URL.

Troubleshooting

Use this error message lookup table to quickly identify the cause and fix for common authentication errors.

Related Features

• Admin: Authentication -- Configure LDAP, OIDC, and local authentication providers
• Credentials: Vault -- Manage the encrypted credential vault and access permissions
• Credentials: SSH, Passwords & Keys -- Store and manage SSH keys and passwords for device authentication
• Credentials: Certificates -- Certificate-based authentication and CA management
• API: Authentication -- API authentication endpoints, token management, and refresh flow
• Troubleshooting: Connection Issues -- If authentication succeeds but the connection itself fails