Troubleshoot Login

This article provides both visual and written instructions for analyzing login-related issues.

Due to the security built into Reveal applications, all users need to be authenticated and all their actions need to be authorized. The main component for user authentication is Keycloak (KC) and all the users' actions are authorized based on their assigned user rights stored in a database server.

KC will store user project association using groups. Other identifiers such as a user’s role in a project remain stored within the relevant App connecting to KC. Essentially, KC is used to allow a user to log in and figure out what projects they are on. Additionally, all user alteration mechanisms are routed into KC, for example, changing a user's email address or name. 

There is a continuous flow of security-related information between the user workstation (browser session), Reveal IIS webserver, Keycloak or Okta, for example, the database server that holds the security information, back to the IIS, to Review, to Processing and back and forth in the opposite direction. If we add to the mix larger deployments, we may have multiple components of the same functionality, making authentication more complex.

If during this flow of information anything gets out of sync, user access might be denied. 

Non-IT Troubleshooting

For troubleshooting on your team's side (non-IT): What has worked well in the past, and is fairly simple: have the user clear their browser cache. Users tend to open multiple windows at the same time and jump from one to another. As a result, sometimes the browser gets confused. 

​As a rule of thumb, if one user has a problem it is user related; if many users have the same problem it is server related. All servers record events in log files, so when we investigate we usually look there first in order to get an idea of what the problem is.   

IT Troubleshooting

Debugging this can be difficult due to the nature of the system. Ultimately, as long as you’re getting your configuration from the well-known endpoint that will handle most issues.

1. Networking: Make sure that both KC and the user in their browser can talk to the client’s identity provider (IDP). KC will do some key exchanging with the IDP, so it needs to be able to talk with it; then the user needs connectivity to the IDP so they can log in on that side.

2. User Information: This requires careful preparation and logging, particularly for large numbers of clients. The main problem is that it can be deceptively difficult to figure out where KC is going to pull user information from. Here’s a process for debugging this:

   1. KC by default will use the User Info URL if provided to pull user infor­mation (username, email, etc.). Make sure that this endpoint is providing what you expect it to be providing.

   2. KC by default will not store user access tokens when a user logs in. This can be altered by changing a setting in KC’s IDP configuration:

   3. If you do this, you can have a user log in as a test, then grab their access token out of KC’s database. Below is the table from which you can get this information:

   4. This is important, because after you store and retrieve this token, you can use it to query the IDP’s User Information endpoint to figure out what’s actually getting sent over.

   5. Additionally, KC has debug options in its configuration XML that will dump userinfo information into logs when a user logs in: https://lists.jboss.org/pipermail/keycloak-user/2015-July/002608.html. Specifically this section:

      >>> <subsystem xmlns="urn:jboss:domain:logging:3.0">

      >>> <console-handler name="CONSOLE">

      >>> <level name="DEBUG"/>

      >>> <formatter>

      >>> <named-formatter name="COLOR-PATTERN"/>

      >>> </formatter>

      >>> </console-handler>

      >>> 

      >>> <logger category="org.keycloak.social.user_profile_dump">

      >>> <level name="DEBUG"/>

      >>> </logger> >>> ...

   6. That way if you’re unsure what’s going on, you can look at KC’s logs to get further information on what’s getting sent. This requires a full server restart to pick back up.

   7. The above was all about how to figure out what information KC is using. Now the problem is how to use that information to link to the right fields in KC. That mapping is found here:

   8. What you want to do is figure out what field should be linking to username and email and create the appropriate mappers to handle it. For example, this is how to set up the email for this identity provider:

Last Updated 8/23/2022