Docker Compose: Local Auth to OIDC Migration Guide

This guide walks through updating your Hoop.dev Docker Compose deployment from local JWT authentication to OIDC (OpenID Connect) authentication with your identity provider.

Prerequisites

• Existing Docker Compose deployment with local authentication
• Access to an OIDC-compliant Identity Provider (Auth0, Okta, Google, Azure, AWS Cognito, JumpCloud)
• Admin access to configure the Identity Provider

Current Local Auth Configuration

Your current .env file likely contains:

# Local JWT Authentication
JWT_SECRET_KEY=<your-secret-key>
AUTH_METHOD=local
API_URL=http://<your-vm-ip-or-host>:8009
GRPC_URL=http://<your-vm-ip-or-host>:8010
POSTGRES_DB_URI=postgres://<user>:<pwd>@<host>:<port>/<dbname>

Step 1: Configure Your Identity Provider

Before updating Docker Compose, configure your Identity Provider with these settings:

Required Redirect URIs

• Sign-in redirect URI: {API_URL}/api/callback
• Sign-out redirect URI: {API_URL}/api/logout

Replace {API_URL} with your actual API URL (e.g., https://hoop.yourdomain.com)

Collect Required Information

You'll need these values from your Identity Provider:

• Issuer URL (e.g., https://your-domain.auth0.com/, https://dev-12345.okta.com/oauth2/default)
• Client ID
• Client Secret
• Audience (optional, depends on provider)

Step 2: Update Environment Variables

Option A: Individual Environment Variables

Update your .env file to replace local authentication with OIDC:

# Remove these local auth variables
# JWT_SECRET_KEY=<your-secret-key>
# AUTH_METHOD=local

# Add OIDC configuration
IDP_ISSUER=https://your-idp-issuer-url
IDP_CLIENT_ID=your-client-id
IDP_CLIENT_SECRET=your-client-secret
IDP_AUDIENCE=your-audience-if-required
IDP_CUSTOM_SCOPES=additional,scopes,if,needed

# Keep existing configuration
API_URL=http://<your-vm-ip-or-host>:8009
GRPC_URL=http://<your-vm-ip-or-host>:8010
POSTGRES_DB_URI=postgres://<user>:<pwd>@<host>:<port>/<dbname>

Option B: IDP_URI Format (Alternative)

You can use the URI format which takes precedence over individual variables:

# URI format configuration (replaces individual IDP_* variables)
IDP_URI=https://client-id:client-secret@issuer-host?scopes=openid,profile,email&groupsclaim=https://app.hoop.dev/groups

# Keep existing configuration
API_URL=http://<your-vm-ip-or-host>:8009
GRPC_URL=http://<your-vm-ip-or-host>:8010
POSTGRES_DB_URI=postgres://<user>:<pwd>@<host>:<port>/<dbname>

Step 3: Provider-Specific Examples

Auth0

IDP_ISSUER=https://your-domain.auth0.com/
IDP_CLIENT_ID=your-auth0-client-id
IDP_CLIENT_SECRET=your-auth0-client-secret
IDP_AUDIENCE=https://your-api-identifier

Okta

IDP_ISSUER=https://dev-12345.okta.com/oauth2/default
IDP_CLIENT_ID=your-okta-client-id
IDP_CLIENT_SECRET=your-okta-client-secret
# Add _userinfo=1 if Okta doesn't allow external token validation

Google

IDP_ISSUER=https://accounts.google.com
IDP_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
IDP_CLIENT_SECRET=your-google-client-secret

JumpCloud

IDP_ISSUER=https://oauth.id.jumpcloud.com/
IDP_CLIENT_ID=your-jumpcloud-client-id
IDP_CLIENT_SECRET=your-jumpcloud-client-secret
# JumpCloud requires userinfo endpoint validation

Step 4: Configure Groups (Optional)

To propagate user groups from your Identity Provider:

In your Identity Provider:

Add a custom claim named https://app.hoop.dev/groups to include user groups in the ID token.

In your .env file:

# If using custom group claim name
IDP_CUSTOM_SCOPES=groups

Using IDP_URI format:

IDP_URI=https://client-id:client-secret@issuer-host?groupsclaim=https://app.hoop.dev/groups

Step 5: Restart Docker Compose

Stop the current deployment:

docker compose down

Verify your .env file:

cat .env

Start with new configuration:

docker compose up -d

Check logs for any errors:

docker compose logs -f hoop

Step 6: Test Authentication

1. Navigate to your Hoop.dev instance: http://<your-host>:8009
2. You should be redirected to your Identity Provider's login page
3. After successful authentication, you'll be redirected back to Hoop.dev

Troubleshooting

Common Issues

Redirect URI Mismatch:

• Ensure redirect URIs in your Identity Provider exactly match: {API_URL}/api/callback

Invalid Issuer:

• Verify the issuer URL is correct and accessible
• Some providers require specific paths (e.g., /oauth2/default for Okta)

Token Validation Errors:

• For providers like JumpCloud or some Okta configurations, add _userinfo=1 option

Groups Not Syncing:

• Verify the groups claim is properly configured in your Identity Provider
• Check that groupsclaim is set correctly in your configuration

Validation Commands

Check environment variables:

docker compose exec hoop env | grep IDP

Check container logs:

docker compose logs hoop | grep -i auth

Rollback Plan

If you need to rollback to local authentication:

Stop containers:

docker compose down

Restore .env file:

# Remove IDP_* variables and restore:
JWT_SECRET_KEY=$(openssl rand -hex 32)
AUTH_METHOD=local

Restart:

docker compose up -d

Best Practices

• Backup your .env file before making changes
• Test in a staging environment first
• Use strong client secrets generated by your Identity Provider
• Enable group propagation for better access control
• Monitor logs during and after the migration
• Document your specific Identity Provider settings for future reference

Post-Migration

After successful OIDC integration:

1. Remove old local user accounts that are no longer needed
2. Configure group-based access controls for connections
3. Set up review workflows using Identity Provider groups
4. Test connection access with different user groups
5. Update documentation with new authentication flow

This completes the migration from local JWT authentication to OIDC authentication in your Docker Compose deployment.