Setting Up Microsoft OAuth for Your App

This guide will walk you through the process of setting up Microsoft OAuth 2.0 authentication for Eva integration using Azure Active Directory.

Prerequisites

• A Microsoft Azure account
• Admin access to your Azure Active Directory tenant
• Your application's domain (e.g., https://eva.foxio.io)

Step 1: Register Your App in Azure AD

1. Go to the Azure App Registration portal:
   https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps

2. Click New Registration.

3. Fill in the registration details:

   • Name: Enter a descriptive name for your app (e.g., "Eva OAuth Integration")
   • Supported account types:
     • Select "Accounts in this organizational directory only (Single tenant)" for internal organization users
     • Select "Accounts in any organizational directory (Multitenant)" for broader access
   • Redirect URI:
     • Select Web from the platform dropdown
     • Add the callback URL: https://eva.foxio.io/api/callback
     • You can add more redirect URIs later if needed

4. Click Register.

5. After registration, note these important values from the Overview page:

   • Application (Client) ID - You'll need this for configuration
   • Directory (Tenant) ID - Required for single-tenant applications

Step 2: Configure API Permissions

1. In your app's settings, navigate to API Permissions (found in the left menu under "Manage").

2. Click Add a permission > Microsoft Graph.

3. Select Delegated permissions and add the following:

   • openid - Sign users in and read their profile
   • email - View users' email address
   • profile - View users' basic profile

4. After adding permissions, click Grant admin consent for [Your Organization] if you have admin privileges.

   • If you don't have admin privileges, users will be prompted to consent individually

Step 3: Create a Client Secret

1. Navigate to Certificates & secrets in the left menu.

2. Under Client secrets, click New client secret.

3. Configure the secret:

   • Description: Enter a meaningful description (e.g., "Eva OAuth Secret")
   • Expires: Select an appropriate expiry period:
     • 6 months
     • 12 months
     • 24 months
     • Custom (up to 2 years)

4. Click Add.

5. IMPORTANT: Copy the client secret value immediately. You won't be able to retrieve it later.

   • Store this secret securely
   • Never expose it in client-side code or version control

Step 4: Configure Authentication Settings

1. Go to Authentication in the left menu.

2. Under Platform configurations, verify your Web platform settings:

   • Redirect URIs should include your callback URL
   • Enable ID tokens under "Implicit grant and hybrid flows" if needed

3. Under Advanced settings:

   • Set Allow public client flows to No for web applications

Step 5: Understanding the OAuth Flow

The Microsoft OAuth 2.0 endpoint URLs for your app will be:

• Authorization endpoint:
  https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize

• Token endpoint:
  https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token

Replace {tenant-id} with your Directory (Tenant) ID.

Step 6: Security Best Practices

1. Client Secret Management:

   • Store the client secret in environment variables or a secure secret management system
   • Set up secret rotation before expiry
   • Monitor Azure AD sign-in logs for suspicious activity

2. Least Privilege Principle:

   • Only request the permissions your app actually needs
   • Remove unused permissions

3. Conditional Access:

   • Consider implementing Conditional Access policies for additional security
   • Require MFA for sensitive operations

Step 7: Testing Your Configuration

1. Test the OAuth Flow:

   • Initiate authentication from your Eva app
   • Verify redirect to Microsoft login page
   • Log in with a test account from your organization
   • Confirm successful redirect back to your callback URL

2. Verify Token Contents:

   • Decode the ID token to ensure it contains expected claims
   • Verify the email and profile information is present

Troubleshooting

Common Issues:

1. "AADSTS50011: Reply URL mismatch" error:

   • Ensure the redirect URI exactly matches what's configured in Azure
   • Check for trailing slashes and protocol (http vs https)

2. "AADSTS65001: Consent required" error:

   • Admin consent may be required for the requested permissions
   • Check if your organization has consent policies in place

3. "AADSTS700016: Application not found" error:

   • Verify the Client ID is correct
   • Ensure the application hasn't been deleted

4. Missing user information in tokens:

   • Confirm the correct scopes are being requested (openid email profile)
   • Verify the user has an email address in Azure AD

5. Client secret issues:

   • Check if the secret has expired
   • Ensure you're using the secret value, not the secret ID

---

Configuration Summary

Use these values to configure Eva app in Slack:

• Client ID: Your Application (Client) ID
• Tenant ID: Your Directory (Tenant) ID
• Client Secret: The secret value you copied

For more information, refer to Microsoft identity platform documentation.