## Options

Following environment variables are used by the software.

**Compulsory**
| Setting | Description |
| - | - |
| OIDC_PROVIDER | URL to your OIDC provider. AuthService expects to find information about your OIDC provider at `OIDC_PROVIDER/.well-known/openid-configuration`, and will use this information to contact your OIDC provider and initiate an OIDC flow later on.|
| AUTHSERVICE_URL_PREFIX | AuthService expects end users will be able to access its Web-based UI from the outside world at `AUTHSERVICE_URL_PREFIX`. Usually, it's in the form of `<APP_URL>/authservice/` It expects that your API Gateway will route any URL that starts with `AUTHSERVICE_URL_PREFIX` (@yanniszark) to it, so it can expose its default Web-based UI and API endpoints. AuthService will use this value to auto-generate sane defaults for a number of settings, including `HOMEPAGE_URL`, `LOGOUT_URL`, and `AFTER_LOGOUT_URL`. The default value, `/authservice/` will work out of the box with an Istio `VirtualService` specifying `/authservice/` as its `prefix`. |
| CLIENT_ID | AuthService will use this Client ID when it needs to contact your OIDC provider and initiate an OIDC flow. |
| CLIENT_SECRET | AuthService will use this Client Secret to authenticate itself against your OIDC provider in combination with `CLIENT_ID` when attempting to access your OIDC Provider's protected endpoints |

**Optional**
| Setting | Default | Description |
| - | - | - |
| REDIRECT_URL | `AUTHSERVICE_URL_PREFIX/oidc/callback` | AuthService will pass this URL to the OIDC provider when initiating an OIDC flow, so the OIDC provider knows where it needs to send the OIDC authorization code to. It defaults to `AUTHSERVICE_URL_PREFIX/oidc/callback`. This assumes that you have configured your API Gateway to pass all requests under a hostname to Authservice for authentication.
| CLIENT_NAME | `AuthService` |A user-visible description for AuthService as an OIDC Client. It is recommended that you set it to a user-visible name for the application/domain that AuthService protects, e.g., `MyApp`. AuthService will *not* use this as part of contacting your OIDC Provider, but it
will use it to auto-generate user-visible message in the frontend. , e.g., "You are now logged out of MyApp. Click here to log in again." |
| OIDC_SCOPES | `openid` | Comma-separated list of [scopes](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) to request access to. The `openid` scope is always added. |
| SERVER_HOSTNAME | `<empty>` | Hostname to listen for judge requests. This is the server that proxies contacts to ask if a request is allowed. The default empty value means all IPv4/6 interfaces (0.0.0.0, ::). |
| SERVER_PORT | `8081` | Port to listen to for judge requests. This is the server that proxies contacts to ask if a request is allowed. |
| SKIP_AUTH_URI | `<empty>` | Comma-separated list of URL path-prefixes for which to bypass authentication. For example, if `SKIP_AUTH_URI` contains `/my_app/` then requests to `<url>/my_app/*` are allowed without checking any credentials. Contains nothing by default. |
| CA_BUNDLE | `<empty>` | Path to file containing custom CA certificates to trust when connecting to an OIDC provider that uses self-signed certificates. |
| AFTER_LOGIN_URL | `<originally visited url>` | URL to redirect the user to after they login. Defaults to the URL that the user originally visited before they were redirected for login. For example, if a user visited `<app_url>/example` and were redirected for login, they will be redirected to `/example` after login is complete. |
| HOMEPAGE_URL | `AUTHSERVICE_URL_PREFIX/site/homepage` | Homepage of the application that can be accessed by anonymous users. |
| AFTER_LOGOUT_URL | `AUTHSERVICE_URL_PREFIX/site/homepage` | URL to redirect the user to after they logout. This option used to be called `STATIC_DESTINATION_URL`. For backwards compatibility, the old environment variable is also checked.|

The AuthService provides a web server with some defaults pages for a `homepage`
and an `after_logout` page. The following values are about these pages. To
learn more about how these pages work, see [the templating guide](docs/templates.md).

By default, this web server listens at port `8082` and its endpoints are:
| Endpoint | Description |
| - | - |
| `/site/homepage` | Landing page |
| `/site/after_logout` | After Logout page |
| `/site/themes` | Themes |

To expose the web server in an environment like Kubernetes with Istio, you need to:
- Create a Service pointing to the AuthService's web server port (8082).
- Create an Istio VirtualService to match traffic with the `$AUTHSERVICE_URL_PREFIX`
path-prefix and direct it to the Service you created. Usually, the `AUTHSERVICE_URL_PREFIX`
is in the form of `<url>/<path>` (e.g,. `<url>/authservice`). Make sure your VirtualService
captures requests with the `<path>`.

| Setting | Default | Description |
| - | - | - |
| WEB_SERVER_TEMPLATE_PATH | `web/templates/default` | A comma-separated list of dirs to look under for templates. Templates with the same name override previously registered ones. For more information, see [the templating guide](docs/templates.md). It always contains the default templates. |
| WEB_SERVER_CLIENT_NAME | `AuthService` | A human-readable name for the client. Used in the web server's pages. |
| WEB_SERVER_THEMES_URL | `themes` | URL where the themes are served. Theme assets are found under `WEB_SERVER_THEMES_URL/WEB_SERVER_THEME`. To learn how you can create your own theme, see [the templating guide](docs/templates.md). |
| WEB_SERVER_THEME | `kubeflow` | Path under `WEB_SERVER_THEMES_URL` where the theme assets are served. |
| AUTHSERVICE_URL_PREFIX | "/authservice/" | The URL path-prefix which the admin has allocated for the AuthService web server. For example, the `prefix` match setting in an Istio VirtualService. The AuthService needs to know where it's served, so it can compute correct values for the default `HOMEPAGE_URL` and `AFTER_LOGOUT_URL`. `HOMEPAGE_URL` defaults to `AUTHSERVICE_URL_PREFIX/site/homepage`. `AFTER_LOGOUT_URL` defaults to `AUTHSERVICE_URL_PREFIX/site/after_logout` `AUTHSERVICE_URL_PREFIX` is added to the `SKIP_AUTH_URI` list. |

OIDC-AuthService stores sessions and other state in a local file using BoltDB.
Session store-related settings:

| Setting | Default | Description |
| - | - | - |
| STORE_PATH | "/var/lib/authservice/data.db" | Path to local session store. Backed by BoltDB. |

OIDC AuthService can add extra headers based on the userid that was detected.
Applications can then use those headers to identify the user.

| Setting | Default | Description |
| - | - | - |
| USERID_CLAIM | "email" |Claim whose value will be used as the userid (default `email`). |
| USERID_HEADER | "kubeflow-userid-token" | Name of the header containing the user-id. |
| USERID_PREFIX | "" | Prefix to add to the userid, which will be the value of the `USERID_HEADER`. |
| USERID_TOKEN_HEADER | "" | Header in which to put the `id_token` for the upstream to find. |