OAuth2 Configuration
Understand the generic OAuth2 configuration in Portabase.
Portabase supports dynamic addition of OAuth2 providers through a series of AUTH_SOCIAL_* variables. This page explains the general operation, available variables, and role management.
Quick Setup
Enable a provider
Define a Client ID and Client Secret pair for the provider of your choice (e.g., Google, GitHub).
Deploy
Apply these environment variables to your Portabase instance.
Configure Callback
Add the redirect URL in the provider's console:
https://<your-domain>/api/auth/callback/<providerId>
Verify
Test the connection from your dashboard login page.
Configure with the CLI
If the dashboard was created with the Portabase CLI, add the provider with portabase dashboard auth add. Supported providers: google, github, discord, apple, linkedin, x, reddit.
portabase dashboard set ./my-dashboard url https://backup.example.com
printf '%s\n' "$GITHUB_SECRET" | portabase dashboard auth add ./my-dashboard oauth github \
--client Iv1.0123456789 --secret-stdin --title "GitHub"
portabase restart ./my-dashboardThe command writes AUTH_SOCIAL_<PROVIDER>_CLIENT, AUTH_SOCIAL_<PROVIDER>_SECRET and AUTH_SOCIAL_<PROVIDER>_TITLE. Map roles with portabase dashboard set ./my-dashboard role_map "admin:admin,default:user".
List and remove providers with portabase dashboard auth list and portabase dashboard auth remove.
The CLI prints a callback URL ending in /api/auth/sso/callback/<providerId>. For OAuth2 providers, register the URL shown in Quick Setup instead.
Configuration Variables
You can configure a "default" provider via AUTH_SOCIAL_* or multiple providers via AUTH_SOCIAL_<NAME>_*.
Prop
Type
Linking a provider to an existing account is controlled by AUTH_ALLOW_LINKING, and a user's ability to detach it afterwards by AUTH_ALLOW_UNLINKING. Both are described in Account Linking.
Dynamic Providers
To add multiple services, use the AUTH_SOCIAL_<PROVIDER>_* prefix. The providerId will be the lowercase version of the prefix.
# Example for Google
AUTH_SOCIAL_GOOGLE_CLIENT="xxx"
AUTH_SOCIAL_GOOGLE_SECRET="yyy"
AUTH_SOCIAL_GOOGLE_TITLE="Google Enterprise"If you use standard names (google, github, discord, etc.), Portabase automatically applies the corresponding icon and brand color.
Role Management
The AUTH_ROLE_MAP variable allows mapping your provider's groups/roles to Portabase's internal roles. It uses the format remote_role:portabase_role, separated by commas.
admin:admin: Maps the remote "admin" role to the local "admin" role.default:user: Sets the default role if no match is found.
Full example: admin:admin,editor:member,default:user
Configuration Guides
Choose a provider to see its specific configuration steps:
Last updated on