Auth0 Application Setup Guide

This guide provides detailed instructions for creating and configuring an Auth0 application for OAuth authentication with Eva, including all necessary settings and security best practices.

---

Table of Contents

• 1. Create or Edit Application
• 2. Configure Application Settings
• 3. Advanced Settings Configuration
• 4. Credentials and Organizations
• 5. Security Best Practices
• 6. Testing Your Configuration
• 7. Troubleshooting

---

1. Create or Edit Application

1. Log in to the Auth0 Dashboard:
   Navigate to the Auth0 management console.

2. Go to Applications:
   Click on the Applications section from the sidebar.

3. Create a New Application or Edit an Existing One:

   • To create a new application, click Create Application.
   • To update an existing app, select the application from the list.

4. Select Application Type:
   Choose Regular Web App as the application type.

---

2. Configure Application Settings

1. Navigate to Settings:
   Once the application is selected or created, click the Settings tab.

2. Set the Application Type:
   Ensure that the application type is set to Regular Web Application.

3. Set the Application Login URI:
   Enter your login URI. For example: https://eva.foxio.io/
   (Replace with your actual domain if different.)

4. Configure Allowed Callback URLs:
   Add the following callback URL:

   https://eva.foxio.io/api/callback
   

   (Replace eva.foxio.io with your actual domain.)

---

3. Advanced Settings Configuration

1. Go to Advanced Settings:
   Within the application settings, navigate to the Advanced Settings section.

2. Configure OAuth Settings:

   • Enable OIDC Conformant:
     In the OAuth settings, ensure that OIDC Conformant is switched ON.

3. Set Grant Types:
   Navigate to the Grant Types section and ensure the following options are checked:

   • Implicit
   • Authorization Code (required)
   • Refresh Token (recommended)
   • Client Credentials (if needed for machine-to-machine auth)

   Note: Do NOT enable "Implicit" grant type as it's deprecated and insecure.

4. Configure Token Settings:

   • Set appropriate token expiration times
   • Enable refresh token rotation for enhanced security

---

4. Credentials and Organizations

1. Navigate to Credentials:

   • Click on the Credentials tab.
   • Select the Client Secret (Post) option to secure your application with a client secret.
   • Copy and securely store your Client ID and Client Secret.

2. Set Up Organizations:

   • Go to the Organizations section.
   • Select Individuals if your application is intended for single-user scenarios.
   • For enterprise setups, configure organization-specific settings as needed.

---

5. Security Best Practices

1. Client Secret Management:

   • Store client secrets in secure environment variables or secret management systems
   • Never commit secrets to version control
   • Rotate secrets regularly

2. HTTPS Requirements:

   • Always use HTTPS for production deployments
   • Ensure all callback URLs use HTTPS

3. Scopes Configuration:

   • The application requires these OAuth scopes: openid profile email
   • Only request the minimum necessary scopes

---

6. Testing Your Configuration

1. Test the OAuth Flow:

   • Initiate an authentication request from your Eva app
   • Verify you're redirected to Auth0 login page
   • Complete authentication
   • Confirm successful callback to your application

2. Verify Token Contents:

   • Check that ID tokens contain required claims (email, profile)
   • Ensure access tokens have appropriate scopes

---

7. Troubleshooting

Common Issues:

1. "Callback URL mismatch" error:

   • Ensure the callback URL in your app matches exactly what's configured in Auth0
   • Check for trailing slashes or protocol differences (http vs https)

2. "Invalid grant type" error:

   • Verify Authorization Code grant type is enabled
   • Check that OIDC Conformant is enabled

3. Missing user information:

   • Confirm the openid profile email scopes are being requested
   • Check that user profiles have email addresses

4. Token expiration issues:

   • Configure appropriate token lifetimes
   • Implement refresh token handling in your application

---

Conclusion

By following these steps, you will have set up an Auth0 application that is properly configured for OAuth authentication with Eva. The configuration uses modern, secure OAuth 2.0 flows with appropriate security measures.

---

Note: Replace https://eva.foxio.io/ with your own domain where applicable. For additional Auth0 documentation, visit Auth0 Docs.