Starting point¶

This document is written with the intent of suggesting tips for troubleshooting issues in production and record known issues.

Tips¶

Some general tips for troubleshooting issues in security services are:

Know the architecture, know the deployment¶

First of all, it is quite important to have a clear idea (an a diagram) about how security have been deployed in this environment (servers, load balancers, private and public domains, ...) and how different components interact between them. Please, become familiar with security architecture documentation.

Health checks¶

Authentication, Authorization and API services exposes a /health endpoint that can be used to troubleshoot issues. A complete report is provided when calling to /health?diagnostic endpoint with an authenticated users or passing a key in the header healthcheck-apikey that matches the one configured for this service in the appsettings.json file at HealthCheckSettings.ApiKey.

Use /health endpoint for checking if service is alive; for example from load balancers.

Logs¶

All logging traces at different levels from Authentication, Authorization and API services are collected at logging database. Please ensure this setting is properly done and the level of traces is the required; if this setting is wrongly configured this will be notified by the health endpoint and no traces will be created in the logging database.

Local log file¶

In some cases, when any of the services even starts, we can investigate the issue enabling the local log files. This can be done editing the web.config file; at location>system.webServer>aspNetCore, set stdoutLogEnabled to true and stdoutLogFile to the folder where the log file must be created. Restart the IIS pool to reload this settings.

 <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*"
             modules="AspNetCoreModule" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments=".\Sequel.Security.Api.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout" />
    </system.webServer>
  </location>