OAuth Authentication
AirTrail supports authentication via OpenID Connect (OIDC). This allows you to use your existing identity provider to authenticate users in AirTrail.
Prerequisites
Before you can configure OAuth authentication in AirTrail, you need to set up an OAuth client in your identity provider. The specific steps to take depend on the identity provider you are using, but in general you will need to:
- Register a new OIDC/OAuth2 client in your identity provider.
- Configure the client with the following settings:
- Client type:
Confidential - Application type:
Web application - Grant type:
Authorization Code
- Client type:
- Add AirTrail's login page as the redirect URI: your
ORIGINfollowed by/login, for examplehttps://airtrail.example.com/login.
The redirect URI must match ORIGIN exactly. Identity providers require
HTTPS for public addresses, so set up a reverse
proxy first. If your provider itself is only
reachable over plain HTTP on your local network, set
OAUTH_ALLOW_INSECURE_HTTP=true.
Configuration
To configure OAuth authentication in AirTrail, either open Settings → OAuth (available to the owner and administrators by default), or configure it through the .env file.
The same settings are available in both the .env file and the settings page.
On startup, AirTrail will check the .env file for OAuth settings and use them if they are present.
Settings that are configured in the .env file will not be editable in the settings page.
| Setting | Env. Var. Name | Default | Description |
|---|---|---|---|
| Enabled | OAUTH_ENABLED | false | Whether to enable OAuth authentication. |
| Issuer URL | OAUTH_ISSUER_URL | The URL of the OIDC issuer (e.g. https://accounts.google.com/.well-known/openid-configuration). | |
| Client ID | OAUTH_CLIENT_ID | The client ID of the OAuth client you created in your identity provider. | |
| Client Secret | OAUTH_CLIENT_SECRET | The client secret of the OAuth client you created in your identity provider. | |
| Token Auth Method | OAUTH_TOKEN_ENDPOINT_AUTH_METHOD | client_secret_post | How AirTrail authenticates to the token endpoint. Supported values are client_secret_post and client_secret_basic. |
| Scope | OAUTH_SCOPE | openid profile | The scopes to send with the request. |
| Prompt | OAUTH_PROMPT | Optional OIDC prompt parameter to send with the authorization request, such as login, consent, or select_account. | |
| Auto Register | OAUTH_AUTO_REGISTER | true | Whether to automatically register new users if no existing AirTrail user is found for the username. |
| Auto Login | OAUTH_AUTO_LOGIN | false | Whether to automatically launch the OAuth login flow when a user visits the login page. To prevent redirection, add ?autoLogin=false to the end of the url. |
| Hide Password Form | OAUTH_HIDE_PASSWORD_FORM | false | Whether to hide the password authentication form when OAuth is enabled. |
| Button Text | OAUTH_BUTTON_TEXT | Log in with SSO | The text to display on the OAuth login button. |
| Allow insecure HTTP | OAUTH_ALLOW_INSECURE_HTTP | false | Allow an identity provider served over plain HTTP. Environment only; use it only on a trusted local network. |
Roles for OAuth users
New OAuth users get the default role. To assign roles from claims your identity provider sends, such as group membership, set up OAuth role mapping.
Last updated on