Skip to main content

Auth0

Introduction​

This guide provides comprehensive instructions for integrating FastAuth into your application using Auth0 as the authentication service. Auth0 serves as FastAuth's primary authentication provider, offering a robust identity platform that handles user authentication across multiple providers while maintaining high security standards.

The Auth0 integration enables secure JWT-based authentication that leverages Auth0's OAuth infrastructure for user management. Through this integration, your application can provide users with seamless social login experiences while benefiting from FastAuth's transaction signing capabilities on the NEAR blockchain.

FastAuth requires authentication through Auth0 for every transaction or delegated action, ensuring that all sensitive operations are properly authorized and authenticated. The JWT tokens generated by Auth0 contain transaction data that is verified against the Auth0Guard contract, providing cryptographic proof of user identity and transaction authorization.

Choose an SDK​

FastAuth provides SDKs for integrating Auth0 authentication into your applications. Choose the SDK that best fits your application architecture:

Browser SDK​

The FastAuth Browser SDK (@fast-auth/browser) is designed for client-side web applications (specially SPAs) and provides comprehensive support for Auth0 integration in browser environments.

Whitelist your application​

To integrate your application with FastAuth's Auth0 service, you must provide specific URL configurations that will be whitelisted in our Auth0 tenant. This whitelisting process ensures secure OAuth flows and prevents unauthorized applications from accessing the authentication service.

Required URLs​

info

You must provide the following URLs when contacting the FastAuth development team

Allowed Callback URLs:

  • The URL where Auth0 redirects users after successful authentication
  • Typically your application's main page or a dedicated callback route
  • Example: https://your-app.com/callback or https://your-app.com

Allowed Logout URLs:

  • The URL where users are redirected after logging out
  • Usually your application's home page or login page
  • Example: https://your-app.com or https://your-app.com/login

Allowed Web Origins:

  • The domains that are permitted to make requests to Auth0
  • Must match your application's actual domain
  • Example: https://your-app.com

Available environments​

FastAuth supports both development and production environments. Specify the environment type in the URL list to development or production.

Configuration Process​

To complete the whitelisting process:

  1. Prepare your URL list: Compile the complete list of Allowed Callback URLs, Allowed Logout URLs, and Allowed Web Origins for both development and production environments

  2. Contact FastAuth team: Reach out to the FastAuth development team with your URL configurations. Include:

    • Application name and description
    • Environment type (development or production)
    • Complete URL list for each category
    • Which SDK you are using

  3. Receive Auth0 configuration: After URL whitelisting is complete, you will receive:

    • Auth0 domain
    • Client ID
    • Audience identifier
    • Any additional configuration parameters

  4. Verify configuration: Test the provided configuration in your development environment before proceeding to production deployment

Security Considerations​

warning

We encourage you to use the development environment to test your application before deploying to production.

  • Ensure all production URLs use HTTPS protocol
  • Limit callback and logout URLs to only those required by your application
  • Regularly review and update URL configurations as your application evolves

Troubleshooting​

Authentication Issues:

  • Verify that your URLs are correctly whitelisted in Auth0
  • Check that Auth0 credentials match the provided configuration
  • Ensure redirect URLs in your code match the whitelisted URLs

Transaction Issues:

  • Confirm you are using the correct testnet contract addresses
  • Verify that the user account has sufficient NEAR balance for transaction fees
  • Check that transaction data is properly formatted

Network Issues:

  • Test with different network conditions
  • Verify NEAR RPC endpoint connectivity
  • Check browser console for detailed error messages