Access troubleshooting

Checking LDAP connection, OIDC, rights assignments, kubeconfig.

Unable to login to GUI/CLI #

• If you log in with root administrator rights, check your credentials (login, password);
• If you log in with user credentials from an external directory (LDAP/OIDC 2.0): — check your credentials (login, password); — log in with root administrator rights (or contact the administrator), check that integration with the external directory is configured and the connection check passes;
• Check that there are user assignments in the platform - access rights specified in the external directory do not create assignments in the platform;

Unable to login to GUI #

• Check the URL (domain, HTTPS);
• Check credentials, LDAP integration or external authentication provider;
• In the command line interface, check the availability of Ingress and the services shturval-frontend, shturval-backend.
• If, after entering the correct credentials, the authentication form is re-opened again without interruption, see Restore login to the GUI.

User is not found when searching #

• Check that LDAP integration is saved and the connection check passes.
• Check base DN to find users and groups.
• Check search filters and attributes: user name (uid, sAMAccountName), group name (cn), email (mail or userPrincipalName for Active Directory), and user and group association attributes.
• Execute ldapsearch manually with the same server URL, connection DN, password and base DN as specified in the platform:

ldapsearch -H ldap://IP SERVER -b "ou=Users,dc=example,dc=com" -D "cn=admin,dc=example,dc=com" -w "PASSWORD"

• If LDAPS is used, check the port, TLS, startTLS and CA certificate.

For more information about LDAP settings, see LDAP Integration.

The group is not found when searching #

• Check base DN for group search.
• Make sure the group name attribute matches the directory settings.
• Check the User and Group Mapping block in the LDAP settings.
• If you are using an external OIDC provider, enter the group name manually: manual entry does not perform an LDAP search.

Permissions do not apply #

• Check the application status in the GUI (red - errors);
• In the namespace shturval-backend look at the pod logs shturval-permissions-operator, container manager for errors;
• Make sure that the access set assigned to the user has the necessary platform permissions for objects: creating and binding clusterrole/role objects directly does not provide access to the GUI. Assign rights only through access sets.

Errors when connecting to LDAP #

• Check URL, port, TLS;
• If CA verification is enabled, check the downloaded trusted root certificate;
• Check the firewall between the platform and the LDAP server.
• For LDAPS, port 636 is typically used. For LDAP without a secure connection, port 389 is typically used.
• If CA verification is enabled, check the downloaded trusted root certificate.

For more information about secure connection, see LDAP Integration.

Kubeconfig doesn’t work #

Invalidity of the token (access token) #

Error: You must be logged in to the server (the server has asked for the client to provide credentials) or couldn't get current server API group list.

Solution:

• Re-download kubeconfig from the GUI;
• Or use kubectl-shturval-plugin to reload kubeconfig.

Invalid certificate in kubeconfig #

Error: tls: failed to verify certificate: x509: certificate signed by unknown authority - can occur if kubeconfig contains a certificate from another cluster.

Solution:

• Re-download kubeconfig from the GUI;
• Or load kubeconfig via kubectl-shturval-plugin.

Kubeconfig export error (connection refused localhost:8080) #

Error: The connection to the server localhost:8080 was refused - kubectl is trying to connect to localhost instead of the address from kubeconfig.

Solution:

• Export kubeconfig to ~/.kube. If the file name is other than config, rename it:

mv /path/to/clustername.conf ~/.kube/config
ls ~/.kube/ | grep config

• Or set the environment variable: export KUBECONFIG=/path/to/clustername.conf.

Time synchronization error #

Error: x509: certificate has expired or is not yet valid: current time ... is before ... - time discrepancy between client and server.

Solution:

• Enable NTP synchronization. Checking and setting:

timedatectl timesync-status # Check NTP
timedatectl set-ntp on # Enable synchronization
timedatectl # Check date and time

• Make sure System clock synchronized: yes and NTP service: active.

General recommendations for kubeconfig #

• The token in kubeconfig has a limited lifespan - when it expires, download a new one or use a plugin;
• Check that the API address in kubeconfig is accessible from your machine (network, firewall);
• For static kubeconfig - make sure the certificates are up to date.

Error in OIDC operation #

Error: You must be logged in to the server (Unauthorized) - possible reasons:

1. Invalid OIDC CA certificate;
2. Unavailability of the management cluster;
3. The user has insufficient rights.

Actions:

1. Check kube-apiserver logs onControl Plane nodes:

crictl logs $(crictl ps | awk '/kube-apiserver/ {print $1}')

If in the logs: oidc: authenticator not initialized or tls: failed to verify certificate: x509: certificate signed by unknown authority - there is a problem with the OIDC CA certificate.

2. If the error is due to a CA certificate: obtain a valid CA certificate (contained in ConfigMap root-ca namespace cert-manager), add it to the Control Plane nodes in /etc/ssl/certs/oidc.crt. If you do not have access to the ConfigMap, contact your cluster administrator.

3. If the problem is not with the certificate: check the availability of the management cluster; If the certificate is valid and the cluster is available, ask the administrator to extend rights.

Debugging OIDC #

If you have problems logging in via Keycloak or Blitz, check the following points.

1. Check Secret with configuration #

Make sure the provider configuration is in Secret:

kubectl get secret auth-idps -n shturval-backend -o yaml

Decode the key value with the configuration (from the output of -o yaml) and check the contents:

# Copy the base64 value from kubectl get secret auth-idps -n shturval-backend -o yaml
echo "BASE64_VALUE" | base64 -d

Check: issuerUrl, client.clientId, client.clientSecret, caBundle (if used).

2. shturval-auth logs #

View authentication service logs:

kubectl logs -n shturval-backend -l app=shturval-auth --tail=200 -f

Look for error messages: invalid_client, redirect_uri_mismatch, invalid_grant, timeouts, TLS errors.

3. Provider URL availability #

Check that the platform can reach the provider:

# From the backend to shturval-backend
kubectl exec -n shturval-backend deploy/shturval-auth -- curl -s -o /dev/null -w "%{http_code}" https://keycloak.example.ru/realms/shturval/.well-known/openid-configuration

Expected 200. For TLS errors, check caBundle or insecureSkipVerify.

4. Redirect URI #

The Redirect URI in the provider must exactly match the URL that the provider redirects to after logging in. Usually this is:

• https://<platform-url>/auth/callback or
• https://<platform-url>/* (if the provider supports wildcard)

Check in the Keycloak/Blitz client settings: Valid redirect URIs and Web origins.

5. client_id and client_secret #

• client_id — must match the Client ID in the provider.
• client_secret — for confidential client must be current. If you change the secret in the provider, update the configuration in ShturvalServicePatch and reapply the Patch.

6. Disabling OIDC when the provider fails #

If the provider is unavailable and you cannot log in:

1. Create a ShturvalServicePatch with AUTH_IDP_ACTIVE: false.
2. Important: The shutdown patch’s patchOrder must be smaller than the OIDC-configured patch for the shutdown to be applied first.
3. Apply Patch and wait for shturval-auth to restart.
4. Log in through the internal authentication form (if SKIP_INTERNAL_AUTH_FORM: false).

7. Common mistakes #

Lack of access to the API server #

Error: The connection to the server XXX.XXX.XXX.XXX:6443 was refused - did you specify the right host or port?

Causes: The API server is not working, is restarting or is blocked (firewall, network).

Action: Contact your platform or cluster administrator to determine the cause.

The plugin does not connect #

• Check the platform URL and credentials in the configuration;
• Make sure that the platform API is accessible from your machine;
• Check the plugin version and compatibility with the platform version.