You should ensure your operations staff knows how to monitor Auth0 service status and has set up a means to subscribe to updates on Auth0 status.
The Auth0 status dashboard together with the Auth0 uptime dashboard shows current and past status of the Auth0 service in a human-readable format. If any monitoring alerts are triggered, and as a first step in troubleshooting, your operations staff should check the status dashboard to see if there is a current outage. The public cloud status page also provides a facility for subscribing to outage notifications, and we also recommend that you check the status of any 3rd party, external services you depend on - such as Social Providers. Having this information handy can help quickly eliminate possible causes when troubleshooting an issue and should be at the top of a troubleshooting checklist for developers as well as the helpdesk staff.
Information on how to check the status of Auth0 as well as any dependent services (such as Social Providers) should be at the top of a troubleshooting checklist for both developers and helpdesk staff, and we recommend you subscribe via the Auth0 status page to set up notification of any status updates.
In the event of an outage to the public cloud service, Auth0 performs a Root Cause Analysis (RCA) and publishes the results on the Auth0 status page. Auth0 performs a thorough investigation after an outage--including a determination of root cause, as well as contributing factors and how to prevent the issue from occurring again--and as a result, an RCA document can take a few weeks to be published.
Email provider setup
You should double check that you have set up your own email provider to support production volumes of emails that might be sent to customers for signup, email validation, account recovery and the like.
Auth0 sends emails to users for events such as signup welcome, email validation, breached password, and password reset events. You can customize the email templates for each type of event, and advanced customization of email handling is also possible. Auth0 provides a test email provider with limited capacity for basic testing, but you must set up your own email provider for production use, and customization of email templates will not work until you have established your own provider.
The default Auth0 email provider does not support sending production volumes of email or customization of email templates. You should therefore configure your own email provider before deploying to production.
If custom code executing in Auth0 (such as in a Rule, Hook, or Custom DB scripts) will call a service inside your network, or if you configure an on-premise SMTP provider in Auth0, then you may need to configure your firewall to allow inbound traffic from Auth0. The IP addresses to allow through the firewall are specific to each region and are listed on the Rules, Hooks, Custom DB scripts, and email provider configuration screens in your Auth0 dashboard (as described in Whitelist IP Addresses).
If this is not handled automatically by your hosting environment, you should have scripts which will automatically restart NTP (Network Time Protocol) if it fails and alerts that will notify someone if NTP is not running. Authentication transactions rely on accurate system time because security tokens may be evaluated as expired when received if there are time discrepancies between sending and receiving systems.
LoadBalancer timeouts checked
If you use the AD/LDAP connector, you should check the load balancer settings in your environment to see if they terminate long running connections that are inactive. If they do, you can modify the Auth0 AD/LDAP Connection settings to use the
LDAP_HEARTBEAT_SECONDS setting to send periodic heartbeat messages to keep the connection open.
If your application maintains server state such that it depends on sticky load balancing to route users to a particular server, it can be beneficial to double check that all load balancer configurations are correct. One load balancer in a pool that is out of sync can cause intermittent errors that are hard to troubleshoot. A quick check of load balancer configuration can avoid such issues in the first place.
You should check that you have set up the ability to capture log data, that logs are covered by your data retention policy and you have mechanisms to enforce logs data retention limits. You should also make sure that your development, support, and security teams know how to access logs data for troubleshooting and forensics purposes. Exporting log files to services that provide comprehensive analytics can help you identify patterns such as usage trends and errors.
Auth0 provides extensive capability when it comes to the logging of events, and also in the scanning of logs in order to identify event anomalies (see logs documentation for further details). Standard log retention period for Auth0 logs is determined by subscription level with the shortest period being 2 days and the longest period being only 30 days. Leveraging Auth0 support for integrating with external logging services will allow you to retain logs outside of this, and will also provide for log aggregation across your organization.
You should leverage one of the Auth0 logs extensions to send log data to an external log analytics service. This will enable keeping data for longer periods of time and provide advanced analytics on the log data.
You should review the log data retention period for your subscription level, and implement a log data export extension to send log data to an external log analytics service. Development teams can use log files for troubleshooting and detecting intermittent errors that may be hard to find via QA tests. Security teams will probably want log data in case forensic data is ever needed. Exporting log files to services that provide comprehensive analytics can help you see patterns such as usage trends and anomaly detection triggers.
Rate limits and other errors
Auth0 provides a unique error code for errors reported when the rate limit is exceeded. You should set up automatic scanning of logs to check for rate limit errors so you can proactively address activity that hits rate limits before it causes too much trouble for your users. Auth0 also publishes error codes for other types of errors, and you will find it helpful to scan logs for authentication errors as well as errors from Auth0 Management API calls (Management API error codes are shown below each call in the Management API Explorer).
Calling the Management API to retrieve user profile information from within a Rule is a common cause of rate limit errors because such API calls can execute for every login as well as periodic session checks.
Be sure to set up proactive monitoring of the Auth0 service as well as end-to-end authentication through your application.
You should establish mechanisms for monitoring Auth0 implementations, so your support or operations team receives the timely information needed to proactively handle service outages. Auth0 provides monitoring endpoints that can be incorporated into your monitoring infrastructure. These endpoints are designed to provide a response suitable for consumption by monitoring services. It should be noted that they only provide data on Auth0. For complete end-to-end monitoring, which is essential for checking the ability of users to log in, we recommend that you set up synthetic transaction monitoring. This will provide greater granularity for your monitoring and enable you to detect outages unrelated to Auth0 as well as degradation of performance, so you can respond more proactively.
You should set up the ability to send synthetic login transactions to facilitate end-to-end monitoring of authentication. You can do this with a simple application that uses the Resource Owner Password Grant in combination with a test user that has no privileges, and don’t forget about Auth0 rate limiting policies too.
You should ensure your team is monitoring all of the following communication channels from Auth0 to stay abreast of important announcements and changes.
There are several different types of notifications from Auth0 that you should watch for as they contain important information that could impact your tenant(s) and project.
From time to time, Auth0 may send an important announcement related to your tenant. These announcements about your service will be sent to your Auth0 dashboard and depending on the severity of the announcement, via email to the registered Auth0 dashboard administrators. You should make a regular practice of logging in to the dashboard and checking the bell icon at the top for any important notices. In addition, you should review emails from Auth0 in a timely fashion as they may convey important information about changes or actions you need to take.
Auth0 security bulletins
Auth0 regularly conducts a number of security-related tests, and if any issues are found, will proactively identify and notify customers who need to make security-related changes. Due to the extensible nature of the Auth0 product, however, it may not be possible for Auth0 to identify every impacted customer, so you should regularly check Auth0 security bulletins. You should make sure a security contact for your organization is listed in Support Center.
It is a best practice to check the Auth0 Security Bulletins page periodically and take the recommended action if you are impacted by any security bulletins.
Auth0 provides information on changes to the service in the Auth0 change log. You should make a regular practice of reviewing Auth0 change logs to be aware of changes. Support teams researching an issue may find it useful to review the change log to determine if recent changes might be related, especially if these are breaking changes. Development teams will also want to review the change logs to identify new features that may be beneficial.
In addition, you should periodically check the Auth0 migrations page for news about upcoming deprecations that might require your team to make changes.
Automated Deployment, version control
While not required, it is highly recommended that you have deployment automation set up. You can respond more efficiently if you need to make any changes after launch if you have automated the ability to deploy and revert changes to dev, test and production environments.
In addition to adopting best practices for change management and QA, successful customers will also integrate Auth0 collateral management as part of some automated deployment process. As discussed in the Architecture section under SDLC support, you will want to ensure you configure separate Auth0 tenants for development, testing, and production environments, and you will want that configuration to be almost identical for the tenant in each environment. Using deployment automation helps ensure this, so that each environment tenant is configured the same, and you will be less likely to see bugs show up as a result of mismatched configurations between environments.
However you configure deployment automation, we’d recommend you unit test your rules, custom DB scripts, and hooks prior to deployment, and run some integration tests against your tenant post-deployment too. For more details regarding this, see the Quality Assurance guidance provided.
Auth0 provides support for a couple of different options when it comes to the deployment automation approaches you can use, and each can be used in conjunction with the other if desired:
- The Auth0 Deploy CLI tooling provides you with an easy-to-use script that can help you integrate with your existing Continuous Integration/Continuous Deployment (CI/CD) pipeline.
- If you can’t integrate directly with, or for some reason you don’t have a CI/CD pipeline, then the Auth0 Source Control Extensions can provide an easy-to-set-up basic automation process with very low maintenance.
Each environment may also need some environment-specific configuration--Application Client ID’s and Client Secrets will be different between the Auth0 tenants, for example--so you’re going to want some way of being able to dynamically reference this rather than having hard-coded values. Auth0 provides support for handling environment-specific configuration information through one of the following two approaches:
Tenant specific variables
Auth0 allows you to configure variables that are available from within custom extensibility; these can be thought of as environment variables for your Auth0 tenant. Rather than hard code references that change when moving code between development, test, and production environments, you can use a variable name that is configured in the tenant and referenced by the custom extensibility code. This makes it easier for the same custom code to function, without changes, in different tenants as the code can reference variables which will be populated with tenant-specific values at execution time:
- For use of variables in Rules, see how to configure values
- For use of variables in Hooks, see how to configure secrets in the editor
- For use of variables in Custom DB Scripts, see the configuration parameters
It’s a recommended best practice to use variables to contain tenant-specific values as well as any sensitive secrets that should not be exposed in your custom code. If your custom code is deployed in GitHub/Gitlab/Bitbucket/VSTS, then using a tenant-specific variable avoids exposure of sensitive values via your repository.
Backup / Restore
You should have a plan and mechanism in place to support any backup/restore capability needed for your project. This can be done using the Auth0 Management API for data as well as the Automated Deployment capabilities described in the automated deployment section for Auth0 configuration.
As noted in the Auth0 Data Tenant Restore policy and Data Transfer policy, Auth0 does not restore deleted tenants or move data between tenants. Auth0 provides the Auth0 Management API to provide customers a completely flexible capability to backup, restore and move data as needed. Customers can write scripts to retrieve data from Auth0 for backup purposes, and similarly write scripts for use with the Automated Deployment capability to restore any aspect of their Auth0 configuration.
Versions Up to Date
You should double check that all technologies in your application stack, as well as browser versions used by your users are on current, up-to-date versions as this will impact Auth0’s ability to provide support if issues arise.
- Check you are using the latest supported version of node.js in Auth0 dashboard settings.
- Check you are using a version of SDK/Libraries supported by Auth0 per the Auth0 Support Matrix.
Certificate rollover plan
Certificates may be used in identity deployments. To ensure a certificate expiration does not catch you by surprise, you should have a list of certificates in your environment along with the expiration dates, how you will be notified when expiration draws near and how the certificate rollover process works.
For SAML connections, you obtain a certificate from the IdP and upload it to a SAML connection for the IdP in your Auth0 dashboard. When one of these certificates is about to expire, Auth0 will send email to dashboard administrators warning of the upcoming expiration. You can obtain the new certificate and upload it using the connection configuration screen.
For WS-Fed connections, if you configure them by specifying an ADFS URL, any changes will be picked up by a daily update. You can trigger an update manually by visiting the connection configuration page in the Auth0 dashboard and doing a Save. If a certificate is changed at the remote IdP, Auth0 can be updated by those mechanisms or by uploading a new metadata file in the same connection configuration screen.
Disaster Recovery / Business Continuity Plan in place
While not an absolute requirement prior to launch, it is useful to have a disaster recovery plan in place to ensure business continuity in the face of different types of disasters, including system outages and natural disasters hitting a region where critical staff is located.
Another item which is not an absolute requirement, but also recommended is to ensure all processes related to Auth0 are documented. This can include the following:
- Change management for configuration
- Deployment of new changes and any automatic deployment mechanisms used, how to revert to previous version if issues found
- Certificate rollover processes, if any
- Adding or removing new Identity Providers, if applicable
- Changes to user profile structure in Auth0 or in directories Auth0 pulls from
- Adding or removing applications or APIs
- Capturing and exporting logs
- Backup/restore process you have implemented
- User management (forgotten password, lost phone)
- Root cause analysis after an incident
Project Planning Guide
We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.