Setting Up Okta OAuth for Your App

This guide will walk you through the process of setting up Okta OAuth 2.0 authentication for Eva integration.

Prerequisites

Log in to your Okta Admin Dashboard:
- For developer accounts: https://dev-XXXXXX-admin.okta.com
- For enterprise accounts: https://yourcompany-admin.okta.com
Note your Okta domain:
- Find your domain in the top-right corner or in the URL
- It will look like: https://dev-123456.okta.com or https://yourcompany.okta.com
- Save this domain - you'll need it for configuration

Navigate to Applications:
- In the Admin Console, go to Applications > Applications
- Click Create App Integration
Select Sign-in Method:
- Choose OIDC - OpenID Connect
- Select Web Application as the Application type
- Click Next
Configure App Integration Settings:

General Settings:
- App integration name: Enter a descriptive name (e.g., "Eva OAuth Integration")
- Logo: Upload your app logo (optional)
Grant type:
- ✓ Authorization Code (required)
- ✓ Refresh Token (recommended)
- ✗ Implicit
Sign-in redirect URIs:
- Add: https://eva.foxio.io/api/callback
- Add any additional callback URLs for different environments
Sign-out redirect URIs: (optional)
- Add your logout redirect URL if needed
Controlled access:
- Select who can access this application:
  - Allow everyone in your organization to access (recommended for internal apps)
  - Limit access to selected groups (for restricted access)
Save the Application

After creating the app, you'll be redirected to the application's page
In the Client Credentials section, you'll find:
- Client ID: Copy this value
- Client secret: Copy this value (keep it secure!)
Important Security Notes:
- Never expose your Client Secret in client-side code
- Store it in environment variables or secure secret management
- Rotate the secret periodically for security

Go to the Sign On tab of your application
OpenID Connect ID Token settings:
- Set appropriate token lifetimes
- Configure refresh token behavior:
  - Rotate token after every use (more secure)
  - Or set a specific lifetime
User consent:
- configure the consent screen

Navigate to the Assignments tab
Assign users or groups:
- Click Assign > Assign to People or Assign to Groups
- Search for and select users/groups
- Click Assign and Save and Go Back
For testing:
- Assign yourself or a test account first
- Verify the assignment is active

Access Authentication Policies:
- Go to Security > Authentication Policies
- Or in your app, go to the Sign On tab > View policy details
Configure session lifetime:
- Set how long users stay logged in
- Configure idle session timeout
Set up Multi-Factor Authentication (MFA):
- In the authentication policy, add a rule
- Configure when to prompt for MFA:
  - Every sign-in
  - Once per session
  - Based on network location
  - Based on user group
Password requirements:
- Set password complexity rules
- Configure password expiration if needed

Default Authorization Server:
- Navigate to Security > API > Authorization Servers
- Click on default authorization server
Verify Scopes:
- Ensure these scopes are available:
  - openid - OpenID Connect authentication
  - profile - User profile information
  - email - User email address
Access Policies:
- Review the default policy
- Ensure your application is included

Your Okta OAuth 2.0 endpoints will be:

Replace YOUR_DOMAIN with your Okta domain (e.g., dev-123456.okta.com).

Test the OAuth Flow:
- Use Okta's built-in test feature:
  - In your app's General tab, click Preview the sign-in page
- Or test from your Eva application
Verify the authentication flow:
- User is redirected to Okta login
- After authentication, redirected back to your callback URL
- Your app receives an authorization code
- Exchange the code for tokens
Check token contents:
- Use jwt.io to decode tokens (for testing only)
- Verify claims include email and profile information

Production Readiness:
- Use a custom domain for better branding
- Enable HTTPS for all endpoints
- Implement proper error handling
Monitoring:
- Review Okta system logs regularly
- Set up alerts for suspicious activities
- Monitor failed login attempts
Compliance:
- Configure session policies per your security requirements
- Implement appropriate MFA policies
- Regular security audits

Common Issues:

"Invalid redirect_uri" error:
- Ensure the redirect URI exactly matches configuration
- Check for trailing slashes and protocol (http/https)
"Invalid client" error:
- Verify Client ID and Secret are correct
- Check if the app is active and not deactivated
"Access denied" error:
- Verify user is assigned to the application
- Check group assignments if using group-based access
Missing user information:
- Confirm the correct scopes are requested (openid profile email)
- Check user profile has required attributes
Token expiration issues:
- Review token lifetime settings
- Implement proper refresh token handling

Use these values to configure Eva app:

For more detailed information, refer to: