How to avoid and troubleshoot an instance lockout

[lauren_boltz]

Author: Sam Asher @sam8 

These steps are for emergencies only. To avoid crises like these, you should always enable alternate login or have backup API credentials for an admin on your Looker instance.

The problem you want to avoid

You  are stuck at the login page and cannot access your Looker instance. This may have occurred because of misconfigured authentication settings, or because users logging in with SAML/LDAP settings have no permissions due to an error with group to role mapping.

To get back into your Looker instance, you need one of the following:

1. A set of credentials that were once valid (email/password or API)
2. Looker Support Access  enabled on your instance
3. A backup of the instance
   • If your instance is hosted by Looker, your instance is automatically backed up five different ways.
   • Customer-hosted instances are not automatically backed up by Looker. See the Creating Backups documentation page for more information about creating backups for customer-hosted instances.

To avoid an instance lockout altogether, ensure that one of the three listed above are enabled. The section below provides a detailed overview of how to troubleshoot an instance lockout, using the listed items above. 

Troubleshooting a lockout

Knowing that you need one of the three items to resolve an instance lockout, we can proceed according to these lockout troubleshooting steps, in increasing order of difficulty to execute: 

1. Do you have Support Access enabled on your instance?
   • If yes, Looker Support can authenticate into your instance and disable the authentication method causing the lockout. You can then log in with your email and password credentials.
   • If no,  proceed with step 2.
2. Does an admin have API credentials?
   • If yes, have an admin log in and use the API endpoint appropriate to the authentication method you use (for example, update_odic_config, update_saml_config or update_ldap_config) to disable the authentication method or enable alternate login for a user. This step will not currently work for instances using Google Authentication  for their Looker instance.
   • If no, confirm whether you have email/password credentials. Skip to step 5 if you do not, otherwise proceed to step 3.
3. Is alternate login enabled for an admin?
   • If yes, have the admin log in and fix the authentication issues that are causing the lockout. 
   • If no, proceed to step 4.
4. Are you using SAML, LDAP,  or OpenID Connect authentication?
   • If yes, Looker Support can disable these authentication methods for your instance so you can log in with your regular email/password credentials.
     • If you want to re-enable SAML, LDAP, or OpenID Connect after the issue is resoled, create API credentials for an admin, and then contact Looker Support to re-enable the authentication method of your choice.
   • If no, proceed to step 5.
5. Do you have a backup of the instance?
   • If your instance is hosted by Looker, the answer is automatically yes. Contact Looker Support to restore your instance from a backup. 
   • If you host your own instance, double-check that you have a backup of the instance and restore from that backup.
   • If no, contact Looker Support for additional assistance. 

If at any point during this process you have questions or need assistance, don’t hesitate to reach out to Looker Support!